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.
Next steps
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.
Follow Rosalie on Twitter and don't forget to sign up for email alerts.
We're currently hiring for developers and web operations engineers. Or drop us a line at gds-recruitment@digital.cabinet-office.gov.uk
4 comments
Comment by Ellis Pratt posted on
API documentation is something that is being discussed a fair bit in the technical writing community. Tom Johnson's blog http://www.idratherbewriting.com probably has the most content, where he has looked at user needs, tools and design patterns (http://idratherbewriting.com/pubapis_design_patterns/ and http://idratherbewriting.com/2015/12/29/trends-technical-writing-2016/). We've also covered API-related topics like markdown on the Cherryleaf blog.
I would say, beware of thinking an auto-generating tools can do it all. Programmers also need overview documentation, guidance on why they need to use something, and getting started information. I'd also suggest you consider what content could be re-used in end-user documentation, and how you would plan to do that. Finally, you might want to get the professional body for Technical Authors, the ISTC (www.istc.org.uk), involved as well.
Comment by Rosalie posted on
Hi Ellis,
Thanks for your interest. We did reach out to Tom Johnson during our research– he does run a fabulous blog and we’re familiar with the content.
And yes, we’re focused on the API endpoint reference section of documentation (which can be auto-generated but still needs to be reviewed), as well as what we refer to as the ‘accompanying documentation’. This accompanying detail includes the overview section, getting started guides, contributor guidelines, etc. Such details can’t be auto-generated, but we’re creating a template so the structure, design and writing style of content can be improved throughout GDS, and hopefully throughout government. Some of the template content will be reusable. Hope this all makes sense. Any further questions, let us know!
Rosalie
Comment by Margaret Eker posted on
Have you investigated the OpenAPI initiative? https://openapis.org/
If so, any thoughts about whether if that initiative will lead to an industry standard where your tool and documentation guidelines might be changed to be more opinionated about recommending specific approaches?
Comment by Rosalie posted on
Hi Margaret,
Yes, we're aware of the recent launch of the OpenAPI initiative. The initiative is currently Swagger oriented and we're currently comparing the benefits of many tools (although we do like Swagger a lot!) Since the initiative is so new (think it was launched in November last year), it's hard to tell how it will develop. But yes, we may recommend more specific appraoches in the future if particular tools are much easier to use and deploy than others. The documentation tool market is growing at the moment and things could change a lot in the next year or so.
Rosalie