Pragmatic ways of keeping documentation up to date

Every leader will tell you documentation is vital for startups and large companies alike. Good documentation builds a body of knowledge that reduces overhead and allows us to learn from the past. But more documentation isn't necessarily better. During technical due diligence audits, we see companies with an unusable amount of documentation. They have a prolific writing culture and fill entire Confluence spaces with articles and diagrams, which poses its own class of problems.

Companies that have too many docs neglect the cost of documentation. These articles have to be written, but they also have to be maintained.

The larger that knowledge base, the more effort is needed to keep the docs up to date. The more articles, the higher the chance of duplicate, outdated, and contradictory content. That internal knowledge base quickly becomes an unusable mess.

Keeping documentation up-to-date can be costly, especially when there is so much of it. Here are a few tips to keep that manageable.

Use one tool

The first step to getting your documents under control is ensuring they are all housed in the same location. While that sounds straightforward, we often see companies that keep their docs on multiple platforms. If the engineers use Notion and the product people write on Confluence, you really should consider picking one. Maintaining a single knowledge base is hard enough. Don't make it worse by having many.

Separate the live from the dead

Not all documents are relevant to everyone, and not all of them follow the same lifecycle. Some are written once and never updated — meeting minutes, for example. Others, such as architectural diagrams, are live documents that must be maintained and adapted as the product grows. Structure your documents with that in mind. Separate the historical logs from the live docs.

Reading tip: Why you should invest in consolidating your documentation

Archive the unknown

Nobody likes to delete articles. It can feel like throwing away valuable work you might need one day. And that's not an invalid concern. Even if a page hasn't been read in a long time, that doesn't mean it's not valuable.

If you're not sure whether an article still needs to be maintained but you don't want to throw it away, move it to an Archive folder. If, after a while, it turns out this still contains vital data, you can easily promote it to a live document.

Move technical documentation closer to the code

Keeping technical documentation up-to-date is tough, as source code changes daily. Trying to keep your company wiki in sync with the git repo is pretty error-prone. Developers will upgrade the database but forget to mention that in the docs.

Moving technical documentation to Markdown files in the git repo makes a lot of sense. The target audience for these docs actively uses the repository. Conversely, those without git access don't care about technical docs. By moving the technical docs closer to the code, missing updates can be caught during code review.

Also read: Why you should code your infrastructure

Always answer with a link

Great companies have built a culture where documentation is a first-class citizen. They habitually check for docs and write them if they are missing. While "build a culture" is not very practical advice, there is something teams can start doing today: always answer with a link.

When a new hire asks about booking a day off, reply with a link to the corresponding chapter in the Employee Handbook. When they start on a new piece of code, don't have a senior engineer walk them through it. Instead, send a link to the right technical documents. If those documents are outdated or missing, write the first draft immediately.

Over time, this habit will spread throughout the company and become part of its culture.

By following these steps, keeping documentation up to date becomes manageable. Every six to twelve months, the team can go through the live documents and see which ones need updating. They can skip the archive and the historical logs and rest assured that the engineers keep technical documentation up to date.

Outdated documentation is often worse than no documentation.

This is the way to keep things under control.

Dive into more documentation tips:

• Five documents every startup should have
• Why operational documentation is more important than you think
• Core Protocols: improving communication within your team
• Why you should code your infrastructure