Technical Writer on GaaP, Jonathan Glassman, recently attended the API The Docs conference, organised by our very own technical writer community at GDS and Write the Docs. Find out what he learned...
API documentation is growing rapidly, not just in technical writing circles, but also within other communities such as developers and product owners. It’s not surprising; a 2013 community survey found that complete and accurate documentation was the most important factor in an API.
Write the Docs is a series of global conferences and local meetups on software documentation. This event was organised so that technical writers could discuss best practices and interesting trends in the field of API documentation. The day itself was divided into several small talks, and also included an unconference session where attendees broke into several groups to talk about different topics. My highlights of the day were the following.
Our own Lead Technical Writer, Rosalie Marshall talked about the challenges of building an API documentation tool and growing the technical writing community at GDS. She detailed what options were looked at for the documentation tool, what the user and department needs were, and why we decided to move from off-the-shelf solutions such as Gelato towards our own tool.
Documenting APIs that are shut down
Daniel Beck, Technical Writer at Aquent, gave a very interesting talk about documenting APIs that are being shut down, and why it’s important to get it right. I really enjoyed this one as most focus on APIs in general is about startup and growth, rather than service deprecation. It contained good practical advice about how, when and what to communicate with your customers to ensure the process is as smooth as possible, as well as which teams to speak to in your organisation to make this happen.
How can API docs be agile?
Jennifer Riggins, Marketing Consultant at eBranding Ninja, dived into the topic of how API docs can be agile. As someone new to both API documentation and the agile methodology, this was extremely useful. Jennifer talked about why documentation is rejected (never enough time, lack of ownership etc.), and how good API documentation takes the user on a journey from “what do you want to do and why” to “you have successfully done this”. She also explained why documentation should not stop a sprint from completing, and how to make documentation easier for developers.
What no-one tells you about documentation
Daniele Procida, Community & Documentation Manager at Divio AG, argued that all documentation could be split into four separate groups, and that the reason that a lot of documentation fails is that it is not categorised in this way.
These categories are:
- tutorials - a learning-orientated lesson to allow a beginner to get started
- how-to guides - a goal-orientated series of steps to solve a specific problem
- discussions - understanding-orientated content that explains background and provides context
- reference - information-orientated content that accurately and completely describes something
His argument that all content can be separated in this way was quite powerful, even if I do have my doubts about whether all content can be so neatly categorised. However, it will be interesting to see if we can make use of this for GDS content.
In summary
As someone who is new to software development, agile and API documentation, this event was extremely useful, and it was really good to feel part of the wider technical writer community. There is so much knowledge to share, and I look forward to more events like this in the future.
Check Write the Docs for more information on upcoming events.
Join us
We are looking for great people to come and work with us and would love to see you apply for a role. If you have more questions about working at GDS you can email our recruitment team.
Help us make government better.
You can sign up now for email updates from this blog or subscribe to the feed.
