How I document — 7 tips for starting, writing and maintaining your documentation

Photo by Aaron Burden on Unsplash

Documentation is one of those topics that elicits a groan whenever it’s mentioned. We all know we need to do it, we all know we should do it, and we will get around it — after we’ve finished this task, or tomorrow, probably.

Documentation is the thing that we will do eventually. But many teams are wasting time and focus by delaying it. Ask yourself how many times you’ve answered the same question via Slack? the ticket that was delayed because we had to wait for someone to get back from vacation? Or that service that went down in the middle of the night and no-one knew how to starting fixing it? How much time was lost through all those occurrences and think through how many times a week, month, a year that is happening in your organisation?

Patrick Kua touched on the topic of documentation in one of his talks and he phrased it wonderfully:

Although, the agile manifesto preaches “Working software over comprehensive documentation” — it doesn’t preach it over no documentation.

Far too many organisations and teams continue to function through tribal knowledge. Tribal knowledge is unwritten information not widely known by many others and results in a slow pace delivery and a lower quality of the product. Good documentation is not a silver…