At Government Digital Service (GDS) we use the docs-as-code approach to write technical documentation. We treat documentation like code by using developer tools to write, review, and publish documentation.
But documentation is not code. We can write tests to confirm code works as expected over time, but we cannot do the same with content. So how can we make sure documentation “works”?
Building a tool to help review documentation
When the GOV.UK developer team refreshed its internal documentation, they realised they needed a sustainable way to keep the new documentation up to date. The periodic review meetings organised by GDS Way contributors inspired the team to set up an automatic reminder to review documentation.
The team needed something to scan the review dates of each documentation page, decide which pages were due for review and alert the page owner. An owner would review the page and could either:
- update the review date, if the content is still correct
- fix out of date content themselves and update the review date
- work with colleagues to fix out of date content and update the review date
Because the GOV.UK developer documentation uses the technical documentation template, developers built the page review features into the template. These features allow users to configure:
- review dates
- content ownership
- showing review banners for each page
- showing links to the source code of each page
Naming the documentation monitor was another challenge. Though initially called ‘The Donkey of Documentation’, the team soon changed the name to create a more relatable character: Daniel the Manual Spaniel. One team member even made a knitted version of Daniel that sits in the GOV.UK support area.
You can find the code for Daniel the Manual Spaniel on GitHub.
Former GDS technical writer Andrea Szöllössi and developers Anshul Sirur and Tijmen Brommet did most of the work to get Daniel up and running.
Making it easy for others to use the tool
Other teams in GDS noticed Daniel the Manual Spaniel and wanted to use it for their own sets of documentation. Setting up Daniel was not straightforward - for each set of documentation, someone had to:
- submit a request to the IT Team to get a Slack webhook
- set up an automated task for Daniel to scan the expiry dates
This process was problematic because:
- setting up involved multiple people
- there was a limited number of Slack webhooks
- different teams had to repeat nearly identical steps
We simplified the process down to teams only having to add the URL for their documentation to Daniel’s configuration. The GDS Reliability Engineering team set up a single Slack webhook and a single automated task that prompts Daniel to check the review dates for all the URLs in its configuration.
Daniel keeps a healthy work-life balance and only checks review dates during weekdays.
Using the tool across GDS
Daniel the Manual Spaniel became popular with the GDS technology community and now reviews 7 sets of documentation across GDS. Some teams set up Daniel for pre-existing documentation, while others set it up when they started writing their documentation.
In general, teams saw an increase in the number of contributions to documentation after Daniel started prompting them to check how up to date the content was.
You can use Daniel the Manual Spaniel, too
You can use Daniel the Manual Spaniel with the technical documentation template, or use Daniel separately.
Have you used Daniel for your docs? Do you have another solution? Let us know in the comments.
1 comment
Comment by Pete posted on
Its a great idea to use GitHub as a docs-as-code repository. Look at how great Microsoft's own use of GitHub is through their own docs.microsoft.com site, and its tight integration with GitHub. They liked it so much they bought the company!