You may have seen our recent blog post about creating best practice for documentation. Now we’re hosting an event for technical writers completely focused on documenting application programming interfaces (APIs), just as we've recently held events around standards and code sharing.
The event is next Friday on the 4 March and will be in partnership with the Write The Docs community, one of the largest networks of tech authors worldwide. Our plan is to discuss API documentation tools, processes, methodologies, tricks and implementation stories.
We hope the event will also be an opportunity for technical authors from within and outside government to discuss some of the challenges they face when writing API documentation.
Good API documentation should make sure integration is an easy and stress free experience for government developers and technical architects. As many parts of government build or rebuild API platforms, this simplicity becomes essential. Without it, service teams risk wasting time on phone calls and meetings as they try to figure out how to implement a platform, or have their questions answered.
API documentation is an area where there is relatively little in the way of industry standards. However this area is fast maturing, particularly as examples of good API documentation surface, and the tools for producing this content develop.
Our Documenting APIs event will host speakers from some of the most popular API toolkits in the industry, including Swagger, API Blueprint and RAML.
The full agenda is below. If you’re interested in attending, please RSVP here to secure your place. The event will take place in rooms at Aviation House.
There will also be a hands-on government developer and technical architect session over lunchtime with an opportunity to discuss Swagger with the chairman of the Open API Initiative, Ole Lensmar. If you are a government technologist interested in attending this, please let us know by writing in the comments below.
Event Preliminary Schedule
9:00 - 09:30 Coffee and networking
09:30- 9.40 Intro and welcome to GDS - James Stewart, Director of Technical Architecture at GDS
9.40- 10.00 Understanding the needs of API documentation users - Rosalie Marshall, Technical Author at GDS
10:00-10:40 Aye, Aye, API - What makes Technical Communicators uneasy about API documentation, and what can we do about it? Ellis Pratt, Technical Communicator at Cherryleaf.
10:40-11:10 Coffee break
11:10-12:00 The benefits to using RAML - Christian Vogel, RAML
12:00-12:40 Swagger and the Open API Initiative - Ole Lensmar, Chairman of the Open API Initiative and CTO of SmartBear Software
12:40-14:00 Lunch break
14:00-14:40 Lightning talks (5- 10 mins each)
- Kristof Van Tomme, Code sample libraries in Drupal, using the GitLab field module.
- Alexander Browne , The HMRC developer portal
- Andrew Marshall - the potential of API docs to evolve technical architecture and API design (TBC)
….more TBC
14:40-15:20 Documenting APIs for Humans - Kyle Fuller, API Blueprint
15:20-16:00 Interactive API documentation - Kim Stebel, Technical Author
16:00-16:40 API docs in DITA - Roger Sheen, Information Architect & DITA Open Toolkit Collaborator, Documentation Maintainer
16:40-17:00 Closing
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.
