https://gdstechnology.blog.gov.uk/2018/12/07/updating-the-gds-technical-documentation-tool/

Updating the GDS technical documentation tool

Two writers looking at content in the technical documentation tool
Technical writers at the Government Digital Service (GDS) create documentation for our platforms and services using
the ‘doc 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.

The technical documentation tool displayed on a desktop and mobile device
The screenshot shows version one of the technical documentation tool on desktop and mobile devices

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
The image shows version 2 of the technical documentation tool
The screenshot shows version 2 of the technical documentation tool with a search box and collapsible navigation

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:

Leave a comment

We only ask for your email address so we know you're a real person