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.