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 bullet to all your problems but it is an underutilised building block to get there.

Documentation can be anything; API contracts, Initiative Requirements, Business Cases or Meeting Minutes — anything that has value or meaning to others inside (or outside the organisation).

Documentation is one of those topics that elicits a groan precisely because we feel guilty for not doing it sooner. We feel guilty because we’re very aware that everything I’ve mentioned above is true. Often, the task seems overwhelming but it doesn’t have to be painful to accomplish. In this article, I share 7 tips for producing more useful documentation, faster, and embedding it into your working routine.

1. Just start —I promise this is not an easy-out answer to open the list, I mean it. Starting can be as simple as creating a new page with the title — this is the most basic building block you need. The simple act of creating a starting…