Think documentation an overhead? Think again…
Recently I’ve been working with a team who were under a lot of pressure to deliver, and one of the options they identified was to drop the documentation they were being asked to write. Why? Because it was an overhead.
After all, good code is sufficient documentation, isn’t it?
Well, that depends… if you’re an early start up and a small team is responsible for everything, then maybe… for a short time… until you hire someone else.
So, why document what you do? So many reasons, for example:
- Identify and reduce/eliminate ambiguity
- Increase efficiency
- Enhance communication
- Capture tacit knowledge and share it
- Provide evidence for audits/due diligence
Who can argue with that? (Well, lots of folk for sure, please be constructive though).
Now that you have been won over to the value of documentation, avoid the temptation to write all the things.
Understand that the value you are looking to derive from documentation is not going to come from duplicating what’s coded. Don’t just translate your logic into English (or whatever lingua franca your organisation has).
The risk is that if you don’t understand what value are looking to derive then you will just end up creating ever more detailed documentation which serves no purpose.
Be clear about the purpose of your documentation, and a good starting point is understanding the audience. Consider the different needs of a new developer in the team, a support operative, a security auditor, or whatever relevant actors there are in your situation.
Susan J. Fowler has some great pointers for documenting microservices written from the point of view of what helps an SRE or support operative in “Production Ready Microservices”. They will take you far. I particularly like the guideline for ops run books – will someone be able to follow this during an incident at 2am?
In a corporate environment, there are some additional things to capture in your documentation:
- What assumptions have you made?
- What choices have you made, and why that choice vs the alternatives?
Here are my suggestions for documentation:
- Treat it as part of the definition of done
- Content > format
- Diagrams can be awesome
- Collaborate on your documentation
- Make it visible and searchable
- Don’t duplicate – refer and link to existing sources
- Keep it brilliantly simple
And most of all, love it, cherish it. It will serve you well in the long run.
