Lean Architecture Documentation

Documentation is always on the extremes. Why? Either a team has no documentation of what so ever or it has documentation paralysis and document every single aspect of the software development process to a point to have waste and slowness and little or no value. IMHO Documentation is part of that group of bad wards like Governance. The reality is Documentation is not what you think it is. There are several ways to document and might not even require to write anything down. Documentation is important. Often people dont know how to deal effectively with documentation and there are so many ways we can extract value from it. So value really depends on the kind of problem we are trying to solve. So let's stop talking about documentation for a moment and let's list some of the problems a software architect needs to help to FIX and then we can revisit documentation later with a freash poblem space lens. Documentation is not about formalizing requirements.

What Problems documentation solve? 

For many people, documentation just has one purpose. Communicating intention. Meaning how this piece of software: which is a component, service, or library works? Yes documentation is about that but is much more and there are many other problems we want to fix such as:

 * Scalability: How we grow the number of engineers (meetings cannot be the answer). 

 * How we make Async work effective? (meetings is not the answer == sync)  

 * How we make sure we engineer improvements happen? (Daily meetings are not the answer) 

 * How we validate that our Strategy and Design decisions are correct?   

 * How we teach consumers(SOA Services) how to use a service endpoint? 

 * How we make onboarding new engineers easier?  

So first of all, if in order to figure out anything you need meetings, you are in deep trouble. Because meetings do not scale. Documentation needs to be seen as an Async enabler. Meaning you can check the documentation(no matter the format) and save you to do meetings for everything. This is not only on COVID-19 times that we leave but also when multiple timezones are involved and/or you do Follow the Sum model. So documentation can help enable async work and scale our work by ultimately killing meetings. Sounds good right? well, there is more. 

Doing Design is important to scale and keep maintenance costs down while delivering constant value at a stable rate. Design is subjective thats true but Debit is real. So how can we make improvements at the code level and communicate that effectively with engineers? Documentation can help with that, not traditional documentation but code docmentation. Several years ago I used to have annotations in the code just so the engineer could talk to each other to Describe technical debt and during code review, we always want to kill some bad code or bad resign(Like the boy's scout rule - always let the place in better shape than you found it). 

Overall Architecture/Design Strategy can be best captured in a Design Document, which could easily be a wiki page or a google docs document. Focusing on Trade-offs you can easily produce a lightweight document with 10-20 pages maximum and use that in a regular review process. 

Consider you are a front-end engineer or you are a backend engineer and you need to call another service outside your team domain. How you gonna do it? What parameters do you need to do? what to expect? Well, thats why we need SOA Governance. We need documentation about the contract both written and code examples. Documentation can also be conveyed as Code with Open API and Swagger.

 As you have new engineers by people coming and going or because your team is growing you will need to do onboarding and that will be painful for you and the new people if you dont have good documentation. 

Mixing Formats 

IMHO we need to work with a mixed format. Text is great but images also are really good to explain how something works. I personally like videos a lot. Slide-casts or simply showing your desktop in a video can be a very powerful way to convey information and your newcomers will thank you for that. 

Text is kind of better because you can read during meetings. However some people dont like text and prefer Videos, some people hate videos. So with mixed formats, you have a better comunication approach but you also tend to work better with different audiences. 

Applying Automation Thinking 

Content needs to be produced. Content will not self-write or self-record but there are other practices we can do to hook things and make documentation easier to consume and make sure we have the atomic habits to make them stick. 

How can we apply automation to make things better? 

* You can automate checklists in Github so they automatically pop up in code reviews. 

* IF you use kanban you can have documentation activities as part of the Definition of Done or in Queue Policies. 

* You can write a scanner and run it in Jenkins to check if projects have required documentation such as Swagger Annotations, Custom annotations for Refactoring - You can even block commits if they are missing. 

* You can scrap your wiki-page and see if there are more characters than before - assuming 1% growth per month maybe? If you send that information to a database you can build a report and even break people's builts if they dont produce docs(the challenge here is to get a good growth rate - but from 0 to 1 is easy).  

* You can ask new engineers to open issues on missing documentation. 

Mindset > Process

Have the mindset to always produce documentation no matter the format(Code, text, or video) it's hard but if you managed to create the atomic habits needed in the long run it will pay off. Automate as much as you can. You code comunication as much as you can. Create meaningful and automated metrics either trigger by commit hooks or Jenkins jobs. Have a central SonarQ that nobody looks at is not the answer.  IMHO Creating a BOT who Slack engineers can be much more annoying and therefore more effective. 

My proposal is we use automation not only to verify things are happening at Scale but also to create the habit hooks atomically so people keep doing that. That's how things work. If you dont have the hooks and just have a process - often will work for a while but will stop with growth or in long run. 

So the mindset is more important than the process. Creating Habits is easier with automation. Dont worry much about getting the right thresholds, you might never get them right, worry about creating the habit.   

Cheers,

Diego Pacheco