API docs in DITA and Markdown

I was recently invited to speak in London at the Write The Docs mini-conference on Documenting APIs hosted by the UK’s Government Digital Service, the team behind the GOV.UK website.

This all-day event featured presentations on API design and documentation solutions like API Blueprint, the RESTful API Modeling Language (RAML), and the Open API Initiative (formerly known as Swagger). The day began with a look at the needs of API documentation users and how API docs differ from other forms of technical communication. The afternoon continued with a series of lightning talks and case studies on various approaches to documenting APIs.

In my talk I proposed a hybrid approach to API documentation that combines Markdown output generated by API docs tools with more complex content authored in DITA and published via the DITA-OT Markdown plug-in for delivery via GitBook or other Markdown-based publishing systems.

The slides are available on Speaker Deck, and embedded below for convenience.

Judging by the level of interest and lively discussions, I think we can look forward to more opportunities to bring technical communication experts and developers together, and build on the knowledge and tools we have to produce better API docs.