As technical writers at GDS we create technical documentation which includes instructions and supporting content for the products we build. We want to make our documentation consistent across all products, but also make it easier to work closely with our subject matter experts and our agile delivery approach. To achieve this, we manage our documentation in the same way a developer would manage code, known as a ‘docs as code’ approach.
An introduction to docs as code
Docs as code means applying software development processes and tools to technical documentation. We write our content in a plain text format using a text editor rather than a markup language like XML and a content management system. We publish with a static site generator rather than an expensive or bespoke publishing system.
Behind the scenes, we manage all of our content via GitHub, which helps us version our documentation and match the way our developers work with code, following a Git workflow. Much like the developers we work with, we write, review, test, merge, build, deploy and iterate constantly.
Why we like docs as code
It has been common practice for technical writers to manage sets of documentation via large publishing systems. This doesn’t work for us. We’re trying to deliver more understanding to our users as quickly as we can using the minimum content.
We also need a way of publishing that can support:
- our fast product evolution
- frequent releases
- collaboration between technical writer, subject matter experts, and users
We’re embedded in our product teams. We sit alongside our developers, architects and web operations colleagues to write out documentation together. Docs as code means we can collaborate even more by using the same tools and processes they do. By working in the open, anyone can contribute to our documentation, and the whole team has shared ownership of the content. It’s a deliberate departure from a more traditional model where a technical writer might sit in another department writing documentation using a different project management approach to their technical experts.
And by using Git for version control and GitHub to host our documentation repositories, we can iterate our documentation alongside our products and make sure they stay in sync. This means we can:
- be sure the user always sees the most up to date version of the documentation
- track every change
- revert to earlier versions if needed
- work on changes independently before merging into the master content
- backup and restore our content
In practice
Many of the product teams at GDS use, or are migrating to, a docs as code approach. For example, on GOV.UK Platform as a Service, anyone can submit a pull request against the documentation, such as a request to document MySQL support. GitHub’s comment threads allow the team to discuss possible changes before merging and updating the live documentation. Some teams choose to keep an eye on incoming requests by automatically posting new pull requests into Slack or other team communication channels.
Improvements to be made
As with any new process, we need to keep tweaking and improving. One of the things we want to do is to scale the docs as code system so that it can be used to efficiently manage high volumes of documentation. We want to make sure we have a process in place for retiring legacy content in the same way that legacy code may be retired to the gds-attic.
Nimble docs for agile delivery
Although we have much to work on, the docs as code approach has hugely improved our documentation processes. More than anything else, the approach matches our general ways of working. We can respond quickly to user needs, work in the open and keep pace with our speedy product teams. We still have work to do to make it scalable and sustainable, but docs as code has brought immediate benefit to our teams and our users.
If you work in government and have an interest in technical documentation, you can get involved by:
- contacting technical-writer-requests@digital.cabinet-office.gov.uk for an invite to the cross-government community on Slack or Basecamp
- leaving a comment below
You can sign up now for email updates from this blog or subscribe to the feed.
