Building a Documentation Culture

“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 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.


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.

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:

Hopefully, these bullets have given you a few jump off points to consider when making process changes to improve documentation.


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:

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.