Is Documentation Like Pineapple on Pizza?

Most Common Problems with Documentation and How to Overcome Them

Internal software documentation is often a controversial topic. Many developers avoid writing it and aim to produce just enough to get the project running. If you browse discussions on platforms like Reddit or Quora, most questions about documentation focus on why it's so poorly done or disliked by developers.

On the other hand, avoiding documentation slows down the team. It creates friction, forcing knowledge transfers to happen in person or requiring developers to reverse-engineer the code just to understand how to use it.

A few pain points make documentation as controversial as pineapple on pizza. Some people love it, others hate it. The goal of this article is to highlight what’s wrong with software documentation and suggest ways to improve it.

Developers Don’t See Immediate Value

Documentation doesn’t bring the same immediate value as shipping new features. There's often a lack of feedback, unlike the kind you get from users, and little recognition within the team for writing documentation. On top of that, documentation in any form can feel like unnecessary overhead. It's easier to justify spending time on high-quality code or thorough test coverage than on basic documentation that could aid future development.

Many developers haven’t yet felt the pain of bad documentation, so they don’t prioritize it. It is the leader’s responsibility to promote documentation by explaining its value and making it part of the team’s deliverables.

Developers Don’t Know What to Write

Most documentation doesn’t need a specific format or template. You simply write down everything you know about a piece of software, then add some headers to make it easier to read. This approach works well for most technical challenges in a project. However, if the topic is more complex and needs to be understood by teams beyond developers, then a more structured format is necessary. You can read about how I created a Design Doc that allowed me to win a new project.

Creating onboarding documentation requires structure because a new joiner can easily feel overwhelmed by too much information at once. Preparing the onboarding process and writing the supporting documentation isn’t easy, but I’ve shared my thoughts on onboarding documentation if you’re looking for some tips.

Developers Don’t Know Which Tools to Use

Documentation tools can be an even more controversial topic than documentation itself. In most cases, the organization decides which tool you’re expected to use. While popular tools for internal documentation may work well for other departments, developers often find them frustrating.

The main issue is that these tools are disconnected from the code. When documentation lives too far from where development happens, developers tend to avoid both writing and reading it.

Documentation is much easier to use when it’s searchable directly from your IDE, or even better, when it shows up in tooltips as you work with the code.

Reviewing documentation is much easier when it’s included in a pull request alongside the related code change. You can take advantage of the existing code review process, whereas with separate documentation tools, you have to find a way to motivate developers to read and review the content.

Using a lightweight tool like Markdown with a simple folder structure encourages developers to create new documents. Adopting Docs as a code approach can help solve many documentation challenges in your project.

Developers Don’t Know How to Maintain Documentation

Some people argue that outdated documentation does more harm than having no documentation at all, and I agree. I've wasted time in my career following READMEs or code comments that were no longer accurate. While this might seem inevitable, a well-thought-out maintenance process can prevent it.

It’s crucial to assign documentation owners. This usually means the original authors or the team responsible for that part of the application. They serve as the point of contact when someone notices an issue or ambiguity.

Most tools display the creation date and the last updated date. These are helpful indicators of whether documentation is being maintained. Based on this, you can establish a periodic review process to either update or deprecate outdated documentation.

Summary

It's hard to make developers love documentation, but you can make it less of a hassle, enough that they start to appreciate its value. It all comes down to enabling developers to write and use documentation effectively by providing the right tools, templates, and processes. I wrote an article about how to enable your team and encourage them to write documentation, with practical advice you can apply.