Last month we hosted our first mini-conference for technical writers, bringing the community together to discuss best practice and tooling. Attendees came from a mix of government departments and agencies, as well as from the private sector.
We held the event in partnership with the Write the Docs community and it was on the specific topic of application programming interface (API) documentation. This was timely for many of our development teams, particularly those that are part of the Government as a Platform programme.
The programme seeks to both speed up and cut the cost of delivering government services by reusing core technology components. Components being built by GDS include GOV.UK Pay and GOV.UK Verify. Both of these have open APIs that need documentation so developers and technical architects can fully understand how they integrate with their government service.
In previous blog posts, I’ve discussed how we’re focused on the user needs of the technical community when it comes to documentation and I went into further details during my conference talk.
Ellis Pratt, a director at technical writer recruitment and training firm Cherryleaf, then kicked off a series of guest speakers with a great opening on the range of skills technical writers need if they want to be successful.
His message was that API documentation writers are like unicorns because they are so hard to find. Companies expect writers to have a high degree of English language fluency, writing experience, as well as a deep knowledge of multiple programming languages. Pratt showed an interesting slide (below) on the different skills needed by traditional technical authors and the new breed of API writers.
We then had a number of presentations from some of the main specification formats for REST APIs, including Swagger, RAML and API Blueprint.
Christian Vogel, community product manager at Mulesoft, introduced the open source RESTful API Modeling Language (RAML) as a solution for API design first approaches. He explained why RAML used the YAML language and showed how easy it was to convert YAML files to a Slate webpage. We have actually tested Slate at GDS using a Swagger to Slate converter but unfortunately had difficulty converting the swagger.json file to a Markdown file. This test was done on GOV.UK Pay to try and mimic the succesful documentation design we’ve seen on sites such as Stripe and GoCardless.
Ole Lensmar, chairman of the Open API Initiative, gave an overview of the Swagger specification and its documentation-related tooling and workflows. He also updated the audience on what they can expect from the new Open API initiative. Meanwhile Kyle Fuller, a developer at API Blueprint, presented the specification as being the most human because of its reliance on the Markdown format. He also gave attendees an idea of the API Blueprint roadmap.
There were a series of lighting talks with speakers from HMRC and Companies House discussing tools they use for API documentation. Technical author Andrew Marshall talked about the potential of API documentation to evolve architecture and design, while Kristof Van Tomme, an advisory board member of the Drupal Association, presented on Drupal code sample libraries, when using the GitLab field module.
The afternoon then continued with a talk from technical author Kim Stebel on interactive API documentation, which allows users to make requests against the API and execute code snippets (all while on the documentation site). Information architect and DITA Open Toolkit collaborator, Roger Sheen completed the day with a very convincing presentation on why the Darwin Information Typing Architecture (DITA) holds a place in API documentation.
We hope to hold more technical author events at GDS and if you or anyone you know is interested in speaking, please get in touch now by leaving a message in the comments below. We can then make sure ensuing events are as diverse as possible.
You can follow Rosalie on Twitter, sign up now for email updates from this blog or subscribe to the feed.
If this sounds like a good place to work, take a look at Working for GDS - we're usually in search of talented people to come and join the team.
3 comments
Comment by Ellis Pratt posted on
I'm glad you enjoyed my presentation - thanks!
Comment by Kristof Van Tomme posted on
Thank you Rosalie for making it happen! It was your interest in API documentation that got this all started. We are doing something similar on the Sunday before Write the Docs Portland. Any chance you could make it? http://www.meetup.com/Write-The-Docs-PDX/events/230291799/
We also need to work on that unconference we discussed 🙂
Comment by Rosalie Marshall posted on
Great Kristof! Wish I could make it but it's not very easy to get there 🙂 Will you be recording the sessions again?