There are misunderstandings about what good developer documentation looks like. This often means it's not prioritised as much as the product that’s being developed. This isn’t just a problem within government but also affects the IT industry, and we hope this trend is beginning to change.
Developer documentation tends to be a reference section that lists all the functionality of a product in detail, as well as information on a product’s concept, how-to tutorials and sample code. Good documentation should make sure that integration is an easy and stress free experience for government developers and technical architects. As the Government as a Platform programme takes off, this simplicity becomes essential. Without it, departments risk wasting time on phone calls and meetings as they try to figure out how to implement a platform, or have their questions answered.
You can see what a low priority documentation is, when you look at the numerous poorly written examples online. GDS plans to raise the bar within government by setting some developer documentation best practice.
Creating documentation best practice
The first step to creating best practice for documentation involved user research with 30 members of the technology community, all of whom were technical architects, service managers and developers (typically the main audience for this documentation).
We showed the users examples of current government documentation and asked them how it could be improved in terms of structure, design and writing style. We also did a card sorting exercise, where users pointed to topics they’d like to see in documentation, and those they'd find less helpful.
A ‘diary study’ was an additional tool used in our research. We asked users to keep track of the documentation they accessed in one week, listing all the good and bad points.
We also contacted some private sector companies who have great developer documentation, such as GoCardless and Stripe. We asked them questions about the process they used to put their documentation together, how they generated their API reference content and the tools they used to publish. Interestingly, all of these companies responded saying they had built their own tools to generate and host their content. This may be something we consider doing in the future.
Challenges to creating a standard
One challenge we came across in our research was how to produce API documentation best practice for government when there isn’t yet an API standard. However, like the rest of the IT industry, government is generally adopting a RESTful approach to platform APIs (you’ll be hearing more about this soon). So we focused our research efforts on how best to document a REST API, and the best tools to use in the process.
Researching documentation tools was a big project in itself. Tools for REST APIs range from documentation auto-generator tools like Swagger, RAML, I/O Docs and API Blueprint to fuller frameworks that will help you develop a web service API, like Enunciate (this works with Javadoc to generate the documentation), and Tyk, an API gateway and management platform. There’s also an increasing number of documentation publishing tools like Slate, Readme.io and Gelato.io, although many of these tend to be proprietary.
Our research on documentation tools is evolving and the documentation guidelines won’t specify the use of a specific tool. Instead we’ll produce guidance on the pros and cons of some of the most popular kits out there.
So where are we with the research now? We’re currently writing up the main findings from our user research and using that to inform the write-up of GOV.UK Pay documentation. We’re drafting guidance on how to write documentation, which includes a template for structuring the content. Finally, we’re putting together a technical content style guide that will build on the GDS style guide.
We’ll be user testing our GOV.UK Pay documentation and our draft general guidance on writing documentation for government. Once we’ve incorporated enough user feedback into these documents, we’ll share the guidance with the rest of government. We hope that writing good technical documentation will soon be mandatory for any government service with an open API.
We also want to set up a technical author community. So, if you’re a technical author working within government, or a developer/content designer tasked with writing developer API documentation, we’d love to hear from you. We plan to hold an event at the end of March 2016 where we’ll showcase our research and hear from other technical authors on the work we’ve done so far.