What to write down, what to create, and to come up with the terms of those documents is always out of date
I recently joined a new team. A whole new company actually. I am now an engineer working at Policygenius – the leading online insurance marketplace (in the US at least). I’ve enjoyed the change so far; It was badly needed.
When you join a new team – and a new company – there Much One of the things to learn. Most of this learning starts with lots of things to read, including process documentation, system diagrams, API specifications, and data models for software teams. Then there are more documents about culture, how to respond to incidents, and decision records.
He. She It could be a lot.
While going through our engineering team’s documentation, I had some advice on how documentation works properly – and why it’s so hard to do. Today, I want to share my views as I am still new as an engineer recently joined.
And just to be clear, I was blown away by the method Hassan The documents in Pg (Policygenius) were. I don’t think there wasn’t a question I asked that didn’t have an answer with a document, wiki, or slide presentation to help me understand the answer in more depth.
And that each one needs a different medium or coordination to be effective. For example, system diagrams and data models should be captured in a visual format – for example, boxes and arrows to show relationships and data flows rather than text descriptions. On the other hand, expectations about how the team will operate and the responsibilities of individual engineers are best described in clear prose.
One of the best things I’ve seen to help with this is a flowchart to help the entire organization agree on what types of documents should live in what types of formats. While these decisions are very intuitive, they can help remove as many distractions as possible. Better yet, add where Documents must be and What are the tools? To be used in every type. Should text documents be stored in a Google Doc or Wiki? Should project folders be under team directories or within the root directory? Should we use the A or B chart tool? In the world of documentation, the more consistent you are with these kinds of decisions, the easier it will be to discover them and add them later to your documents.
When describing software systems, we Must Trust the code on the documents. why? Because the code is being What your program does. There is no way to avoid that.
This is why engineers can be pedantic about comments. Comments explaining what the code does can easily become outdated and confuse the next engineer trying to change it (or even understand it). I won’t open comment wars here, but it’s nice to be aware that your code serves as a form of documentation for your program – because is being your program.
Therefore, part of the admins’ responsibilities is to look at the code when asking a question about system behavior. When a discrepancy arises between what the documentation says versus what the code does, the team must decide which is incorrect and correct it. Maintaining a tight loop here is especially important for public APIs and API specifications (which we’ll discuss in more detail shortly). Either way, when a gap is identified, don’t be silent. Pose the problem and work to understand what the code does and decide what needs to be changed – the code or documents.
Since the code is the truth, anything we can do to keep the documentation coherent with our code is usually a good idea. If you can create documents From your code, you reduce documentation aberration as much as possible. Tools like JavaDoc or godoc make it easy to convert comments in code to HTML, text, or even
man Program pages. Standards like yuml allow teams to store and understand easily changeable text documents in UML diagrams.
These tools, along with continuous integration and web based API, can allow you to create documentation from your source with every commit to your code mainline. Just think how awesome it is! Every time you change a data model, a new ER diagram is created and stored in your team’s Wiki! These low friction tools can change the way your team works.
One caveat here is that you also need to take into account the difference between contract/specification and other documents. You want to direct your software requirements from specifications and contract definitions, but you also want to have documentation about your software.
This topic is particularly relevant to the API lifecycle – have you been building your documentation from source code since then is being What does your API do? Or do you push the documentation from your specs because this is your API Must to do? Opinions vary on this, but the one thing to remove here is that the specification documents for your software need to be handled differently than the documentation for your software.
The sad truth is that even if we build awesome processes and automations to keep our documentation up to date, the truth is that at some point, something will need to be updated. Some links will be broken. The section will be out of date and invalid. Legacy documentation may not be true for more stable systems, but for the ever-changing world of modern web applications, it will.
Instead of avoiding it, choose to reduce it and be quick to make changes when you notice something is wrong. Everyone in your organization should have some ability to suggest changes quickly and effectively or have the ability to make the changes themselves. Treat your documents like an Agile product: Make it easy to get feedback and make edits so you can respond quickly to the changing needs of your growing team.
After all this, remember:
- Documentation is a tool to help your team succeed.
- Effective documentation will tell your team members what you do, how you do it, and most importantly, why.
- Go to the code when you can – create anything possible to reduce drift.
- Make documents easy to change – just like code.