Improve technical documentation

How many times have you heard, “smart team, but the project has no documentation.” Or “I think this is the framework our team needs, but the documentation is out of date.”

Why is inferior such a prevalent problem? Why are the docs always out-of-date? There are three reasons why your team’s documentation probably sucks:

There are no professional rewards tied to writing documentation
Many developers don’t want to work on a project that doesn’t have clear metrics of if their outputs are good or bad
Documentation is hard to maintain

There are no professional rewards tied to improving technical documentation

Writing documentation can harm a developer’s chance of earning a promotion.

Developers are prized for writing new features. Early in your career, the more new code you write, the better. Granted, when you write all this code, you need to be careful not to create too much technical debt or bring down too many servers.

It’s considered a disadvantage to write prose, during your first three years as a software developer. Workplaces have a silent hierarchy of what’s regarded as a prestigious task and what is just grunt work. When working in an engineering department, writing your own in-house frameworks and tooling is at the top. QA, customer service, and writing documentation is considered at the bottom of this pyramid. Of course, every workplace is not like this, but many engineering departments operate like this.

This phenomenon is so common that it has a name, being glue. The name originates from the term ‘glue code.’ Glue code is code that ties two very different parts of the codebase. It plays a supporting role, as opposed to a starring role. Being glue in an engineering team means that you are doing a lot of supporting jobs, but none of these tasks will help you earn a promotion come review time. Great documentation may help your company, but not in a way that directly helps your career. Good documentation converts customers, but the sales department reaps that benefit, but not the engineer. Good documentation will help reduce the number of tickets filed, but that benefit is reaped by the QA department, but not the engineer.

In some companies, writing documentation is a wasteful for career development. If you’re on the bottom rung of the engineering org and want to optimize for climbing the career ladder, writing documentation is not the best use of your time.

Many developers don’t know where to begin or how to measure what is “good” documentation

Let’s say that your engineering team embraces a documentation-driven culture. Where in the heck should they begin? Many software developers are unsure how to write effective documentation that doesn’t should like “an engineer wrote it.” What does good documentation look like? How do you measure it?

Disorganized Documentation

There’s very little guidance on what technical documentation should sound like. Terms of the trade such as “database join” or “provisioning the database” without a proper explanation can be confusing to front-end engineers. Proper UX research tactics such as conducting user interviews or information architecture card sorts are woefully absent from the documentation writing process.

Little time investment in writing documentation leads to disorganized docs. In a 90-day sprint, an engineering team will spend 89 days writing and deploying features and writing documentation the last day. Anyone who goes back to the docs a month or two later may have difficulty following along because the information has no structure.

Documentation is meant to solve a problem. Readers can’t solve problems if they have difficulty searching for the solution. Good documentation is well organized and makes it easy for the reader to find. The discipline of organizing content is informational architecture. We’ll cover this topic more in-depth later on in the book.

“Sounds like an engineer wrote these docs”

Great documentation has a uniform voice. Many developers don’t know how to determine that their tone is off. Implementing a style guide helps engineers, project managers, and the QA team write in a common voice.

Documentation is hard to maintain

Out-of-date documentation plagues many well-meaning engineering teams. Why is this such a common problem? And what can you do about it?

Technical documentation that lives outside of the codebase can hinder contribution efforts. “Out of sight, out of mind” is a genuine problem. Many software engineers spend most of their time on Github. If your documentation lives in a CMS or (god forbid) Microsoft Word, the platform switch is too much for developers to overcome.

The most straightforward solution is to adopt a docs as code philosophy where the documentation lives with the codebase.

Troublesome maintenance is also a cultural problem. Documentation has to be owned, just like a feature or code base. It’s not good enough to proclaim that “up-to-date” documentation is important. Updating documentation has to be a part of sprints and tickets. There should be a name next to the person who will ensure that the checkout API documentation will stay up to date.

Why is this important?

Ok, we’ve pointed out how developers find writing documentation to be an annoying and messy chore. So what?

Good documentation can make or break a partnership with a major company. Poor documentation blocks you from signing that next contract or becoming an 8 figure company. Over 80% of team leads admit that they make their purchasing decisions based on documentation quality.

You can’t skimp on quality documentation. What does good documentation look like?

Good documentation doesn’t forget that there is a human behind the machine.
Good documentation is brimming with empathy.
Good documentation respects timing. They know that the developer is going through a funnel, and different concepts need to be introduced at the right time.

How to Improve Technical Documentation

Bad documentation is not inevitable. There are ways that your team can improve your technical documentation. The key is to make:

Reward developers who write documentation
Define what is ‘good’ documentation
Automate documentation maintenance

Professional Rewards

Engineering teams need to acknowledge technical writing. Suppose you want developers to write. Carve out some time to complete documentation. Tie bonuses and promotions to documentation goals.

Define What is ‘Good’ Documentation

‘Good’ documentation doesn’t have to be subjective. If you want your documentation to be consistent, create a style guide. A style guide is a list of technical writing rules and best practices. There are some excellent style guides for free, so you don’t have to worry about creating one. Some of the technical style guides that stand out include:

Automate Documentation Maintenance

Finally, automate as much of the documentation process as possible. Use linters like Vale and Github Actions to comb through your prose. Do You want to keep your documentation up to date? Put it through the same CI/CD process as your code.

Why Your Team Can't Improve Technical Documentation

Table of contents