5 ways to keep internal tech documentation up to date
Over the last year we’ve been improving the developer documentation on GOV.UK. The goal of this is to make it easier for developers to do their job.
1. Make it easy to find
There should be only one place to find documentation. Internally we use the
publishing.service.gov.uk domain, so we decided on using docs.publishing.service.gov.uk for the internal docs. The site is publicly accessible, because making things open makes them better. Making the docs open means that it’s easy to find on Google as well.
There are a few other entry points. The GOV.UK chrome extension links to the content schemas, document types and application pages. Every repository on GitHub links to the docs.
2. Keep docs close to code
The closer the code is to the documentation the more likely it is a developer will update it. Of course, this conflicts with the previous principle of having a single place for everything.
We deal with this by pulling in the docs from GitHub. For example: the content-store docs are copied from GitHub directly.
3. Automate docs generation
Docs shouldn’t only be prose. Because all GOV.UK repos are open, we have the opportunity to integrate code, data and configs into the docs.
For example: the page that describes all fields in the search API is constructed by fetching the definitions that are used in the application. This means it never goes out of date.
Another example are application pages such as this. They use the GitHub API to fetch the repository description and tags.
4. Make it feel good to update
Updating docs isn’t the most fun thing. To create a sense of achievement, it helps if the docs themselves look nice.
We’re lucky to have the tech-docs-template, which provides a well designed, responsive, accessible, user researched template for tech docs. You can read more about it on the GDS blog.
5. Have a formal review system
Implement a system that forces you to keep it up to date.
On GOV.UK each page has a “review by” date. For more on that, continue reading about the review system in a previous post.