Most teams reach an inflection point where good documentation is essential to its productivity. Still, it’s hard to write documentation that is relevant, accessible, and ages well over time.
Having seen several teams struggle or succeed with writing documentation, here are a few behaviors that I found make a difference.
Be selective about what you document and what you don’t.
When teams get in the spirit of writing documentation, it’s tempting to document everything. Doing so, however, leads to noise that is a burden to maintain over time.
Here are some litmus tests for whether something is worth documenting:
Be picky. Be explicit about why something is worth documenting. Documentation isn’t free; you bear a one-time cost for writing it and a recurring cost for maintaining it forever.
Understand the reader you are writing documentation for.
Identify the target audience at the beginning of your documentation so readers can confirm reading it is worth their time. Call out what knowledge the documentation assumes the reader has and share links to introductory resources.
When introducing new terms, emphasize them in bold so it’s easy to find their definitions. A glossary is a good complement to this.
Bias towards simple over clever. No one understands the information like you do. When writing the documentation, you should feel like you’re “dumbing it down”.
Structure your documentation to accomodate the different levels of investment with which readers will approach it.
A few readers will read your documentation from beginning to end. Most readers will skim the headings and dive deeper into only the sections that interest them.
To accomodate this range, use headings and subheadings liberally. Add a table of contents to orient the reader. Hyperlink sections of the document to each other whenever possible. Keep paragraphs short; avoid “walls of text”.
Layering communication enables readers to start shallow and go deep into parts when needed.
Implement practices that help your documentation age well over time.
Code, systems, and processes change quickly. Maintenance of documentation is essential to keep it fresh, and there are things you can do as the original author to grease the wheels for future maintainers.
Be concise. Don’t repeat yourself. Maintainers should have to update the same information in as few places as possible.
Explain why things are the way they are. This will help future readers decide for themselves what is still true instead of trusting your bygone context.
Link to “sources of truth” liberally. When quoting a metric, link to the query that generated it. When presenting an org chart, link to the original illustration so that maintainers can update the documentation after a re-org.
Signpost your documentation with time markers. Use phrases like “As of April 2018” to caveat information you anticipate going out-of-date. If something is subject to change, call it out.
Encourage a culture of collective ownership over all documentation on the team. This way, the burden of maintenance is distributed over more people.
Host “documentation sprints” to dedicate time for your team to write and maintain documentation. This has the second-order effect of making the team feel like they own the quality of it.
Recognize documentation contributions whenever possible, especially during performance reviews. Good documentation contributes to project impact when it levels up the productivity of the team.
Encourage readers to leave the documentation better than how they found it.
January 2020