What is documentation? Why is it important? What makes it good or bad? And – if it’s bad – what are the consequences? In this article, I’ll discuss all of this, explain how documentation (good or bad) is an outgrowth of organizational culture, and suggest some ways you can work to improve culture and produce better docs – even in the face of organizational resistance.

What is documentation? And what does it do? 

One of the main things documentation does is guide our users. Reading docs is a critical part of user experience. You can think of documentation as starting down in the code, with comments; then climbing a ladder through end-user product guides and feature maps, installation, user onboarding and QuickStart guides, recipes and examples of use, and more extensive tutorials.

Beyond this, you may still be talking to primary users, but often to potential customers, too. Coherent documentation also tells a technical and business story about your products in context. It talks about benefits of your products, differentiating from competition and establishing thought leadership.

A good documentation culture treats docs as a foundational aspect of both marketing and product. 

Why is good documentation so important? 

Good documentation makes for:

  • Better onboarding, both for customers and new employees. Good first impressions of docs lead to good first impressions of your products.
  • Faster troubleshooting, because everything is written down, which helps retain users and customers.
  • Improved productivity for customers and for your support team. Good docs lead to good product experiences. They prevent mistakes and confusion on customers’ parts (reducing support burdens) and enable faster problem resolution.
  • Better change management, as good docs detail the history, enumerate the impacts, and help you deliver new features without stressing users or support folks.

It also makes for better communications and less wasted labor. Per a recent study by Cornell University of professionals working in distributed teams:

  • 61% say it can be hard to figure out what their colleagues are working on.
  • 44% say that siloed digital media tools made it hard to spot if work is being duplicated.
  • 62% reported missing opportunities to collaborate with their co-workers and achieve better results.

Bad documentation is part of the problem, here – which is fundamentally one of communication. Good documentation, if rigorously maintained, can break down communication silos, eliminate wasted work, and help your people collaborate much better.

What makes documentation good or bad?

Good documentation is:

  • Centralized in one platform:  Bad docs are fragmented and hard to find and align.
  • Easy to understand: Good docs minimize use of jargon and keep language simple (not everyone is fluent in English).
  • To the point; It doesn’t tell you a whole story before trying to tell you what you need to do and what you’re actually looking for. 
  • Good visuals: People inherently look at things that are nice to look at. We want to look at them more and we want to look at them longer. 
  • Easy to read: If your documentation is difficult to read, people aren’t going to be inclined to spend as much time looking at it as they will, if you have very nicely designed, nicely laid-out documentation with interesting things to look at. 
  • Complete, accurate, and up-to-date: There’s nothing worse than undocumented product features, or docs full of inaccuracies.
  • Includes date and author: If there are any accuracy problems, we know when they were introduced and how they happened. We also know how old this documentation is if we run into an error. 
  • Addresses the right audience: If you’re targeting the end user, make sure that that’s the person who’s getting this information. If you’re targeting administrators, make sure you tell them which information they need to know.
  • Free of assumptions about what users know or can do. Good docs point users to introductory resources and guides that help prepare them and give them inroads to a good experience with your product. Bad docs typically presume a lot of pre-existing knowledge. The worst (and we’ve all seen these) seem to be written so that only core engineers working on the project can understand them.

Where do bad docs come from? And what do they cost?

Bad documentation cultures share some hallmarks:

  • Documentation is everybody’s problem and nobody’s job.
  • Experts (e.g., developers) aren’t incentivized to help build and improve docs.
  • The organization (documentation specialists) aren’t available to help experts with the writing and editing.
  • Docs are presumed to be deliverable with projects, but no resources or time are allocated to make this happen. Nor is the need to keep docs updated ever budgeted for realistically.
  • People hoard information – to preserve job security or simply because no disciplined process for extracting institutional knowledge and turning it into documentation exists.

What do documentation failures cost? A lot. According to a recent article by ItGlue, it’s common for employees of technology companies to spend up to 20% of their time searching for information about their own company’s products. If we assume an average salary of $60,000 a year, time lost per employee costs $13,760, with the opportunity cost (dependent on projected employee contribution) typically much higher.

How do you start fixing a bad docs culture? 

In a case study from Google composed in 2016, 48% of Google engineers cited bad documentation as their number one productivity issue. 50% of SRE issues cited problems with documentation.

What worked for Google was changing the status quo. They made documentation radically simpler for their engineers. They made a system that they called g3docs that did the following:

  • Removed decisions, presenting one way to document things. 
  • Centralized and provided a single source of truth and docs tools. G3docs hosted their docs in the source code in Markdown, so that their engineers could stay in their IDs, and work on the documentation at the same time. Their documentation system automatically rendered out that markdown into nice HTML pages. 
  • Leveraged the single source of docs truth – the g3docs team formed alliances with influential engineers to introduce the new docs tooling and partnered with specific teams to build strategic integrations, so that many projects could draw on the centralized docs repo.
  • Released and iterated the documentation system in the open so that everybody knew what was going on.
  • Had teams lead by example. Rather than forcing teams to use the tools, they reached out to some of their most influential employees to get everybody on board.

Methods for culture change

Culture is not immutable. We can change it, but you need to start from the top, choose someone to drive it, and make it easy. 

  • Start from the Top: Start with standardization, and empower your contributors by establishing that clear, concise writing is the expectation from everyone. To do this, ensure that your higher-ups and your stakeholders lead by example, with quality writing. 
  • Choose someone to drive it: Make someone responsible for managing documentation. Even if it isn’t that person’s entire job, make it someone’s official responsibility. This person will also create templates, training, and any other support that’s needed to create the documentation. 
  • Make it easy: Choose tools that integrate into existing workflows. Let developers stay in their editor. The more you can let people stay in the flow that they’re in, the more work they’re going to be able to do. And use version control like Git, so that everyone can contribute easily, and make sure that everyone has access. 

Tools and techniques

These are some examples of documentation tools that I really love, and that are very popular:

  • Markdown is one of the most popular languages for writing documentation. The Read The Docs platform is really great. They allow for the following two documentation systems: mkdocs, which is a fast and simple documentation generator, and Sphinx, which is a more powerful documentation generator that’s really good for technical documentation. 
  • GitBook is a nice platform if you want something that’s not open source and is a little more shiny. 
  • Confluence, which I feel like everyone uses for their internal documentation whether you like it or not, is a really robust system, though also not open source.

Empowering your contributors to use a system that allows for contributions from everyone is one of the reasons things like mkdocs are so popular: they allow for everyone to contribute. And these days, you don’t even need to be able to edit Markdown in an editor – you can use GitHub or GitLab. Their inline editors are absolutely, totally serviceable for things like editing documentation. 

Give training on how to write docs if your team feels like they don’t know how to write or they’re not good technical writers. This will allow everyone to have a sense of ownership over the docs and take pride in knowing that people are reading your documentation. Create a positive feedback loop for people who have historically been resistant to writing documentation and decide to start writing it. Make sure that you thank them that you tell them they did a great job so that they’ll want to do it again. 

If it doesn’t work? There are a few things we can do. We can go the slightly more forceful way and just not accept merge requests that don’t include the documentation updates. Make an expectation that the documentation is just as important as the code. You can also make doc writing an official part of everyone’s job description. Make everyone feel the need to update the documentation and get people to understand that this is the way that people use your product and how they’re going to understand it.