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.
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.
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.
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.
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.