The Government Digital Service has been working on establishing a standard design for its technical (i.e. developer) documentation. This content is for systems architects, developers and users of the GOV.UK platforms and APIs.
You can see an example at: GOV.UK Platform as a Service
Cherryleaf was given a preview of the new design a few months ago, when we ran an API documentation training course at GDS. We made a couple of suggestions, which look like they’ve been included in the final design.
The documentation has these main sections:
- Overview. This includes why you would use it, and the pricing plan.
- Getting started. This includes prerequisites and limitations.
- How to deploy
- Troubleshooting
- Managing apps
- Managing people
Elsewhere on the website is information relating to support, the product features, and the product roadmap.
As with other GOV.UK content, the team carried out research into what developers wanted, and they carried out usability testing. I understand the researchers discovered developers preferred content to be on a long, single page, and that they would be working in a two screen environment. Using long pages enables users to search and navigate with the keyboard, rather than the mouse. GDS also looked at other developer websites, such as WorldPay and Stripe, for best practice.
GDS is highly regarded in the technical communications community for its excellent work on the GOV.UK website. This means it is likely other organisations will copy GDS’s design for their own developer documentation.
Leave a Reply