Technical writers at the Government Digital Service (GDS) create documentation for our platforms and services using the ‘docs as code’ approach.
Before we started using docs as code, GDS teams used a variety of templates like MkDocs to publish technical documentation. But our user research showed our inconsistent documentation designs were putting off users because information was difficult to find.
To fix this problem, the Service Manual team launched the technical documentation tool in March 2017. The design for this tool was based on user research with developers and technical writers. The tool had a single page template, designed to keep API reference information in one place and used the static site generator Middleman.
The first version of the desktop tool had a 2 panel layout with the navigation on the left hand side and content on the right. The mobile version displayed one page at a time and used a table of contents to navigate between content.
Developing our technical documentation tool
GDS teams started using the tool and for API documentation and things like GOV.UK developer docs and internal team manuals. We quickly found the tool was not ideal for presenting large amounts of complex content. As a result, we did some user research which showed us:
- the left hand navigation could become too long
- developers wanted a clearer way to display API reference information and a way to test the API from within the documentation
- some users preferred to use Command+F to search for content, but single pages often contained too much content to make this useful
We ran a 3 month project with an external development team to address these issues. This helped us learn some important lessons for commissioning future updates like factoring in more time to test changes. For example, we only had one week to test the API reference when ideally we would have liked one month.
What’s new in the technical documentation tool?
We’ve added lots of features to the technical documentation tool to address issues highlighted in our user research. The tool now:
- renders HTML content in multiple pages
- automatically renders API reference information
- has collapsible and expandable left hand navigation
- lets users find information across a documentation site using a search box
What we’re doing next
We are currently working:
- with the GDS tech community to maintain the tool
- on user research to see if there are further changes that would help our users
- with other government departments such as the Ministry of Justice so they can also use the tool
If you work in government and have an interest in technical documentation, you can get involved by:
- leaving a comment below
- raising an issue in our Tech Docs template or Tech Docs gem repositories
- joining the technical writing channel on the cross-government Slack
- emailing technical-writer-requests@digital.cabinet-office.gov.uk for an invite to the Basecamp
