Building a Documentation Culture
· #collaboration · #culture · #leadership
“How do you build a good documentation culture in a company?” — that was the question posed by a friend who’s the VP of Engineering at a fast growing startup.
As we do in most situations, more so when talking about culture, we start with the People.
People
People model behaviours that they observe are being practiced by others and that are being rewarded. Those behaviours become your culture.
Good documentation starts with a good writing culture. So you want to make good, clear writing the norm in your organization.
There are plenty of opportunities to model & reinforce a good writing culture. Are your emails well written? When you see someone writing an ineffective email, do you take the time to coach them on writing clear, actionable emails? Are your JIRA tickets well written or just one liners that would be inscrutable to anyone, including the ticket writer after a month? How about presentations that your team creates? Are they being thoughtful in adapting their writing style to the medium?
Writing is a skill and like any other skill, it improves with practice & training. So invest in writing training for your staff! Amazon is known to have a strong writing culture and there’s plenty of internal training that’s provided for employees to learn to write well. Do note that writing well is contextual. What’s well written prose for a period novel is probably not well written for a business document. The training needs to reflect that. In my first job at a scientific research institute, I was sent to a training on writing good scientific papers. It was immensely useful and I put that training to good use in the two journal papers that I subsequently wrote during my tenure there.
Finally, as I mentioned earlier, culture is also what gets rewarded. If you want a good documentation culture, then do factor in documentation work into performance appraisals. While documentation in general should be considered part of the job (and culture!), there are opportunities to call out & reward specific activities, e.g. when a junior employee writes a new piece of documentation or when a senior employee creates/improves a documentation related process.
Process
Which is a good segue into looking at process improvements that you can make to create a good documentation culture.
The goal of a process is to ensure you get the desired outcomes in a reliable & repeatable manner. In the case of documentation, the outcome to strive for is great Quality of documention, i.e., documentation that’s Accurate, Useful and Complete.
- Accuracy means that your documentation reflects reality. So you want processes that help you catch & fix errors in your documentation.
- Useful documentation helps the reader accomplish their goal. So you want feedback mechanisms that inform you whether readers managed to do that.
- Completeness means that there aren’t any gaps in your documentation. Documentation could be useful but not complete (e.g. some features aren’t documented) and vice-versa (e.g. everything is documented but is incomprehensible to the reader).
The processes will vary depending on the quality bar that you are striving for. Given limited time that can be spent on documentation alone, you’d want a higher quality bar on customer visible documentation than internal documentation.
With that mental model, here are some ideas for processes that you can implement:
- Make it easy to create new documentation by creating templates. More on this in the next section below.
- Make it easy to add & update documentation. E.g., don’t prevent other teams from updating your team’s docs - make them world writeable. The risk of incorrect changes is small and easily manageable with version control.
- Pull Requests must include doc changes. If you have a PR review checklist, add “docs updated” to that list as a reminder. Don’t tolerate a “docs will be updated in the next PR” culture.
- Use a written process (e.g. Amazon’s PR/FAQ, Python’s PEP, Oxide’s RFD) to discuss and agree upon major architecture, process or product changes.
- Add automation to check broken links within your documentation, especially for customer facing docs.
- Add analytics and feedback button mechanisms to your doc pages and look at the metrics to assess quality.
- In your customer support system, ensure there’s a “documentation related” tag that can be applied as the root cause when resolving tickets. Measure this ticket count to check progress on your documentation efforts.
- Improve the previous process by ensuring such a support ticket isn’t closed till a related doc fix ticket is created.
Hopefully, these bullets have given you a few jump off points to consider when making process changes to improve documentation.
Product
Finally, we look at the product which in this case, is the actual content of your documentation.
The most important thing you can do here is to figure out how best to organize the content and then create templates around that organizational framework. Your documentation may be Complete, but if it’s poorly organized, it’ll be perceived as neither Useful nor Complete by your readers who’ll struggle to find what they need. Moreover, an organizational structure also significantly reduces friction in creating new documentation since you are not repeatedly spending cycles just figuring out where every new piece of content should live (cf. bike-shedding). This is applicable both for external documentation as well as internal docs.
A good organizational framework is The documentation system which organizes documentation by purpose:
- Tutorials - step by step docs that aid learning for a new comer.
- How-to guides - problem oriented docs that help in accomplishing specific tasks.
- Conceptual - docs providing detailed explanations that aid in building a strong understanding of your system.
- Reference - Informational documentation that provide all the nitty-gritty details.
I often cite the Django project’s docs as an example of high quality documentation and you can see how it follows the above framework.
Interestingly, this framework isn’t limited to just software or technical products. You can easily imagine how you could apply it to say, a podcasting tool or a stock trading platform.
For internal documentation, an area which benefits immensely from investment is organizing operational documentation. This documentation covers aspects like where’s a particular service’s source code, the requirements queue, design docs, deployment processes, monitoring dashboards, SLAs, alarm configurations, on-call rotation, etc. When I was at JPMorgan Chase, one of the first problems that the SRE chapter in my team tackled was to standardize the service documentation so that on-call engineers could quickly and reliably find what they needed when responding to incidents.
Spotify’s Backstage attempts to standardize all of this information so that it’s discoverable at scale. But you don’t need to start with such a system; just take the concepts and then create a few template wiki pages that make it easy to instantiate internal docs for every new microservice that your team spins up.
Architecture documentation is often overlooked in a fast moving environment and struggles to keep up with an evolving system. Here, I recommend the C4 Model as a light-weight system that can help your team maintain high quality architectural documentation. Every four to six months, get your entire team in a (virtual/physical) room for a couple of hours sketching your system’s architecture on (digital/physical) whiteboards or flipcharts using the C4 model. For maximum impact, split your team into two and get each half to document the system independently and then compare their diagrams to identify gaps. Once done, just upload the diagrams as-is to your internal wiki. This exercise not only keeps your docs up to date but is also a fantastic way to deepen your team’s collective understanding of the system and serve as a great onboarding resource for those new to the team.
Being intentional
Good intentions never work, you need good mechanisms to make anything happen. — Jeff Bezos
To create a culture of documentation, communicate your intention and back it up with investments in your people and processes.