Documentation is one of the most valuable artifacts of any technology project or platform. It provides context to new joiners, avoids duplicating responses via Slack/Teams, and facilitates asynchronous communication, but it also requires constant care and feeding.
Confluence is where documentation goes to die
– Unknown
Most of the large enterprises that I’ve worked for have a large corpus of documentation in a wiki of some sort. Most of it is dangerously out-of-date, incomplete, duplicated, and fragmented across different pages or spaces. Documentation of this kind causes countless wasted hours and frustration on the part of the reader. There’s nothing worse than spending days working through a documented process only to discover that you’re following an outdated copy because only wiki admins can delete pages.
I recently opened the developer onboarding page for a project only to find that it was last updated five years ago but it was still being used as the starting point for new developers joining the team. These poor souls floundered around for weeks trying to make sense of the landscape, feeling stupid; isolated; incompetent; all because the docs had atrophied. This situation is easily resolved by telling new team members that their first task is to run through the onboarding page and update it where necessary. Create a Jira ticket for it and assign it to them. Let them report on it during standup. Track the onboarding duration so you can see how your docs are performing.
This lays the groundwork for building a culture of documentation seen at companies like GitLab. People need to know that maintaining the documentation is important and valued, and that they are permitted expected to prioritize it from the outset.
The benefits to maintaining good documentation are well-known:
- Breaks down knowledge silos
- Reduces tribal knowledge
- Reduces project/program risk (see bus number)
- Facilitates asynchronous work
- Reduces workload of key people
Determining which documentation to prioritize is more art than science.
Background information is always useful for new team members to understand what the system does, why it was built, and provides some historical context.
Decision logs provide context about previous technical decisions, and more importantly, the conditions and assumptions that factored into it. This can help the future team know when to re-visit the decision.
How-Tos probably require the most attention but if they’re kept current then they can also serve as a detailed specification for automating mundane or repetitive tasks.
Documentation should be written for a junior team member, new joiner, or a person with little or no context. This insures that all the necessary details are captured. Don’t fall into the trap of writing docs just to jog your own memory - they only have an audience of one. Statements like “if this then do that” should contain all the information to determine when the “if” condition is true or false, otherwise you’re relying on tribal knowledge that the reader may not possess.
Experience is what helps you to recognise a mistake the second time you make it.
Your bug tracker should also be viewed as documentation. For Pete’s sake, don’t ever close a bug report with “Fixed. Please re-test”. Show some respect! Take a minute to describe what caused the problem, how you fixed it, and any other relevant information. You’ll forget the details almost immediately but the bug tracker is there to remind you when you come across a similar defect later.