Documenting APIs

In the beginning of March 2016, the Write The Docs London community did a mini-conference that explored the tools and processes used to document APIs. The conference was organised in cooperation with the Government Digital Services. We recorded the sessions and mashed them up with tweets and summaries.

Documenting APIs

In the beginning of March 2016, the Write The Docs London community did a mini-conference that explored the tools and processes used to document APIs. The conference was organised in cooperation with the Government Digital Services. We recorded the sessions and mashed them up with tweets and summaries.
Join the WTD community

1. Intro and welcome to GDS

James Stewart, Director of Technical Architecture at GDS

Introducing the Government Digital Service and its mission.

Video Recording:

2. Understanding the needs of API documentation users

Rosalie Marshall, Tech Author at GDS

"Good API documentation is essential to the success of Government as a Platform." But who are the users, what do they want? What should be the function of "good docs" and how does it look like in practice? Get the slides here.

Video Recording:

3. Aye, Aye, API - What makes Technical Communicators uneasy about API documentation, and what can we do about it?

Ellis Pratt, Technical Communicator and director at Cherryleaf

Technical authors and API documentation writers: they have different roles and need different skills. And what tools are available for both groups of writers? Get the slides here.

Ellis's reflections on some of his slides.

Video Recording:

4. A Quick Introduction to RAML

Christian Vogel, RAML

RAML makes it easy to manage the whole API lifecycle from design to sharing. Christian Vogel explains the context and possibilities. Get the slides here.

Video Recording:

5. Swagger

Ole Lensmar, Chairman of the Open API Initiative and CTO of SmartBear Software

A framework for APIs: what are its characteristics, how does it work, what are the advantages? And last but not least: meet SwaggerHub for integrated tooling.

Get the slides here.

6. Code sample libraries in Drupal, using the GitLab field module

Kristof Van Tomme, CEO Pronovix

Code sample libraries for collecting, organising and cross linking code samples. An example on the iText site.

Get the slides.

Video Recording:

7. The HMRC developer portal

Alexander Browne, HMRC product manager

The speaker gives us an introduction of the HMRC API Developer Hub. Why did they develop it? What do they want to achieve?

Video Recording:

8. The potential of API docs to evolve technical architecture and API design (TBC)

Andrew Marshall, technical author

What do we have to keep in mind when we are designing? Andrew Marshall explores the possibilities. Get the slides.

Video Recording:

9. Local digital standards for waste service in government

Paul Mackay, Technical Lead for the DCLG Local Waste Service Standards Project

Developing digital standards: Paul Mackay offers an insight into the technical side of the project.

For his presentation, Paul used the Waste Service Standards site for technical specifications and briefly mentioned the Popolo Project and the Smart City Concept Model. You can find additional information about the Local Waste Service Standards Project here.

Video Recording:

10. Introducing Swaggerly

Chris Smith, lead technical architect at Companies House

The speaker introduces the Companies House API site, beta release - its goal is to improve the API and documentation.

Video Recording:

11. Documenting APIs for Humans

Kyle Fuller, API Blueprint

How can you make sure a broad audience will be able to understand your API? What do we have to keep in mind? How can we solve problems? Kyle Fuller shows us how it can be done. Get the slides.

Video Recording:

12. Interactive API documentation

Kim Stebel, Tech Author

What is interactive documentation? Why do we need it? Kim Stebel, not only a technical author but also an API documentation writer, shows us how to use tools like Swagger and Jupyter Notebooks to write interactive documentation.

Get the slides.

Video Recording:

13. "API docs in DITA"

Roger Sheen, Information Architect & DITA Open Toolkit Collaborator, Documentation Maintainer, Infotexture

"DITA meets Markdown": what are the challenges and possibilities for writers?

Get the slides.

Video Recording:

A Write the Docs community event

Documenting APIs was a day-long mini-event organised by the London Write the Docs meetup team in collaboration with GDS.

The Write the Docs community is a community for us, documentarians. Its events are focused on documentation systems, tech writing theory, and information delivery. We consider everyone who cares about communication and documentation and their users to be a member of our community. This can be programmers, tech writers, customer support, marketers, and anyone else who wants people to have great experiences with software.

Our conferences create a time and a place for the global community of documentarians to share information, discuss ideas, and work together to improve the art and science of documentation.

Find out more about upcoming events on writethedocs.org: Write The Docs North America, May 22-24, 2016, in Portland, Oregon Write the Docs Europe, September 18-20, Prague, Czech Republic

API The Docs
Devportal Awards logo
API Resilience
Developer Success

PRONOVIX

RESOURCES

SERVICES

Newsletter

Articles on devportals, DX and API docs, event recaps, webinars, and more. Sign up to be up to date with the latest trends and best practices.

 

Subscribe