## [Documenting APIs, Write The Docs mini-conference London 2016](/documenting-apis-write-docs-mini-conference-london-2016) ```
``` # 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](http://www.writethedocs.org/) ![](/sites/default/files/2022-01/styles/555_half_content/public/api_the_docs_logo_alpha.png?itok=l_1CcwgU) ## 1. Intro and welcome to GDS ### **James Stewart**, Director of Technical Architecture at GDS Introducing the Government Digital Service and its mission. #### **Video Recording:** > [\#GDSapidocs](https://twitter.com/hashtag/GDSapidocs?src=hash) is on! Great inspirational kick-off by [@jystewart](https://twitter.com/jystewart) [\#writethedocs](https://twitter.com/hashtag/writethedocs?src=hash) > > — Kristof Van Tomme (@kvantomme) [March 4, 2016](https://twitter.com/kvantomme/status/705690400917463040) ## 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**](https://www.slideshare.net/secret/Hte9NAjf4zMUNt). #### **Video Recording:** > Great insights about API docs, not only for government use by [@RosalieMarshall](https://twitter.com/RosalieMarshall) [\#GDSapidocs](https://twitter.com/hashtag/GDSapidocs?src=hash) [\#writethedocs](https://twitter.com/hashtag/writethedocs?src=hash) [pic.twitter.com/v9OvDIX2gc](https://t.co/v9OvDIX2gc) > > — Kristof Van Tomme (@kvantomme) [March 4, 2016](https://twitter.com/kvantomme/status/705693376625123328) > [\#GDSapidocs](https://twitter.com/hashtag/GDSapidocs?src=hash) Government as a Platform: > > “We don't want to be building a kitchen every time we need to have a meal.” > > — Roger Sheen (@infotexture) [March 4, 2016](https://twitter.com/infotexture/status/705691464257441793) > Great talk on researching who the users of API docs are, and what they want, from [@RosalieMarshall](https://twitter.com/RosalieMarshall) of GDS. [\#GDSapidocs](https://twitter.com/hashtag/GDSapidocs?src=hash) > > — Beth Aitman (@baitman) [March 4, 2016](https://twitter.com/baitman/status/705699911346556928) > Emerging trend from [@RosalieMarshall](https://twitter.com/RosalieMarshall) and [@ellispratt](https://twitter.com/ellispratt) talk at [\#GDSapidocs](https://twitter.com/hashtag/GDSapidocs?src=hash) [\#writethedocs](https://twitter.com/hashtag/writethedocs?src=hash) event is that we need better tools for API docs... > > — Kristof Van Tomme (@kvantomme) [March 4, 2016](https://twitter.com/kvantomme/status/705704704135860224) ## 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**](http://www.slideshare.net/ellispratt/aye-aye-api-what-makes-technical-communicators-uneasy-about-api-documentation-and-what-can-we-do-about-it). Ellis's [reflections](http://www.cherryleaf.com/blog/2016/03/reflections-on-last-weeks-mini-conference-on-documenting-apis/) on some of his slides. #### **Video Recording:** > Difference in skills required for technical authors and API writers [@ellispratt](https://twitter.com/ellispratt) [\#GDSapidocs](https://twitter.com/hashtag/GDSapidocs?src=hash) [\#writethedocs](https://twitter.com/hashtag/writethedocs?src=hash) [pic.twitter.com/zX6t6IF9ci](https://t.co/zX6t6IF9ci) > > — Kristof Van Tomme (@kvantomme) [March 4, 2016](https://twitter.com/kvantomme/status/705697469921939456) > API docs are a team responsibility. Make them part of the team's review process - same tools [@ellispratt](https://twitter.com/ellispratt) [\#GDSapidocs](https://twitter.com/hashtag/GDSapidocs?src=hash) [pic.twitter.com/NrBvw0VL98](https://t.co/NrBvw0VL98) > > — Beth Aitman (@baitman) [March 4, 2016](https://twitter.com/baitman/status/705703696626278400) > At [\#GDSapidocs](https://twitter.com/hashtag/GDSapidocs?src=hash), [@ellispratt](https://twitter.com/ellispratt) contrasts tools used by tech writers and API docs devs. Key takeaway: both can do more than you may think. > > — Roger Sheen (@infotexture) [March 4, 2016](https://twitter.com/infotexture/status/705704322588401664) > There might be a legal requirement to have API docs in non-English languages [@ellispratt](https://twitter.com/ellispratt) [\#GDSapidocs](https://twitter.com/hashtag/GDSapidocs?src=hash) [\#writethedocs](https://twitter.com/hashtag/writethedocs?src=hash) > > — Kristof Van Tomme (@kvantomme) [March 4, 2016](https://twitter.com/kvantomme/status/705701585888919554) ## 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**](http://www.slideshare.net/ChristianVogel6/api-documentation-meetup-2016-london). #### **Video Recording:** > API docs are not just for developers, managers are reading them now also [@ChristianVogel\_](https://twitter.com/ChristianVogel_) [\#GDSapidocs](https://twitter.com/hashtag/GDSapidocs?src=hash) [\#writethedocs](https://twitter.com/hashtag/writethedocs?src=hash) [pic.twitter.com/z2OvUY9xRd](https://t.co/z2OvUY9xRd) > > — Kristof Van Tomme (@kvantomme) [March 4, 2016](https://twitter.com/kvantomme/status/705717154658828290) > At [\#GDSapidocs](https://twitter.com/hashtag/GDSapidocs?src=hash), [@ChristianVogel\_](https://twitter.com/ChristianVogel_) on RAML for single-sourcing API docs: > > “Write once. Use many. Creative laziness encouraged.”[\#writethedocs](https://twitter.com/hashtag/writethedocs?src=hash) > > — Roger Sheen (@infotexture) [March 4, 2016](https://twitter.com/infotexture/status/705722648710483968) ## 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**](https://drive.google.com/a/pronovix.com/file/d/0B5qtFkXgWYCxQ21HMThPdVdaWHl1cl9ORFlQaXNpWEVoRVNB/view). > Trying you get technical writers involved into the Open API initiative [@olensmar](https://twitter.com/olensmar) [\#GDSapidocs](https://twitter.com/hashtag/GDSapidocs?src=hash) [\#writethedocs](https://twitter.com/hashtag/writethedocs?src=hash) [pic.twitter.com/DY6HG9N9X2](https://t.co/DY6HG9N9X2) > > — Kristof Van Tomme (@kvantomme) [March 4, 2016](https://twitter.com/kvantomme/status/705732344150401028) ## 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**](https://docs.google.com/presentation/d/1Nf3UvQd5AiWqoxJ0fO5BweN9QQba84ANbxUENKEKE0Q/edit#slide=id.ge40efbbf7_1_345). #### **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**](https://www.dropbox.com/s/br4o3nz46xmq0wn/Getting-Creative-API-documentation-meetup-20160304.pdf). #### **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**](http://communitiesuk.github.io/waste-service-standards/) and briefly mentioned [**the Popolo Project**](http://www.popoloproject.com/) and [**the Smart City Concept Model**](http://www.legsb.gov.uk/smartcityconceptmodel/). You can find additional information [**about the Local Waste Service Standards Project here**](http://www.localdirect.gov.uk/product/local-waste-service-standards-project/). #### **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:** > [@baitman](https://twitter.com/baitman) Also the first public release of Swaggerly is on it's way. Used to build [\#GDSapidocs](https://twitter.com/hashtag/GDSapidocs?src=hash) > > — Chris Smith (@zxchris) [March 4, 2016](https://twitter.com/zxchris/status/705805052276043781) > [@baitman](https://twitter.com/baitman) I had such a good response from the talk... clearly time to publish my 8-factor api design guide! Soon! [\#GDSapidocs](https://twitter.com/hashtag/GDSapidocs?src=hash) > > — Chris Smith (@zxchris) [March 4, 2016](https://twitter.com/zxchris/status/705803176981733376) ## 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**](https://speakerdeck.com/kylef/designing-apis-for-humans-write-the-docs-2016). #### **Video Recording:** > API blueprint overview by [@kylefuller](https://twitter.com/kylefuller) [\#writethedocs](https://twitter.com/hashtag/writethedocs?src=hash) [\#gdsapidocs](https://twitter.com/hashtag/gdsapidocs?src=hash) [pic.twitter.com/rBpJJpt81l](https://t.co/rBpJJpt81l) > > — Kristof Van Tomme (@kvantomme) [March 4, 2016](https://twitter.com/kvantomme/status/705773091574644736) ## 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**](https://storage.googleapis.com/interactive-docs-presentation/index.html#1). #### **Video Recording:** > Interactive docs and quick API onboarding experiences drive adoption. [@KimStebel](https://twitter.com/KimStebel) [\#gdsapidocs](https://twitter.com/hashtag/gdsapidocs?src=hash) [\#writethedocs](https://twitter.com/hashtag/writethedocs?src=hash) [pic.twitter.com/fdhAqpngM3](https://t.co/fdhAqpngM3) > > — Kristof Van Tomme (@kvantomme) [March 4, 2016](https://twitter.com/kvantomme/status/705778076131725312) ## 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**](https://speakerdeck.com/infotexture/api-docs-in-dita-and-markdown). #### **Video Recording:** > DITA to [@GitBookIO](https://twitter.com/GitBookIO) transformation demo by [@infotexture](https://twitter.com/infotexture) at [\#GDSapidocs](https://twitter.com/hashtag/GDSapidocs?src=hash) [\#writethedocs](https://twitter.com/hashtag/writethedocs?src=hash) [pic.twitter.com/cBlWk6qOSb](https://t.co/cBlWk6qOSb) > > — Kristof Van Tomme (@kvantomme) [March 4, 2016](https://twitter.com/kvantomme/status/705794226307665921) > Automated publication flows can be a challenge for people not used to them [@infotexture](https://twitter.com/infotexture) [\#GDSapidocs](https://twitter.com/hashtag/GDSapidocs?src=hash) [\#writethedocs](https://twitter.com/hashtag/writethedocs?src=hash) [pic.twitter.com/AdxaS8i9ux](https://t.co/AdxaS8i9ux) > > — Kristof Van Tomme (@kvantomme) [March 4, 2016](https://twitter.com/kvantomme/status/705789342732689409) > Why choose between DITA and markdown if you can have both? [@infotexture](https://twitter.com/infotexture) [\#GDSapidocs](https://twitter.com/hashtag/GDSapidocs?src=hash) [\#writethedocs](https://twitter.com/hashtag/writethedocs?src=hash) > > — Kristof Van Tomme (@kvantomme) [March 4, 2016](https://twitter.com/kvantomme/status/705794565589110785) - [Join Write the Docs London](http://www.meetup.com/Write-The-Docs-London/) ### A Write the Docs community event Documenting APIs was a day-long mini-event organised by the [London Write the Docs meetup team](http://www.meetup.com/Write-The-Docs-London/) in collaboration with [GDS](https://gds.blog.gov.uk/category/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](http://www.writethedocs.org/conf/): [Write The Docs North America](http://www.writethedocs.org/conf/na/2016/), May 22-24, 2016, in Portland, Oregon [Write the Docs Europe](http://www.writethedocs.org/conf/eu/2016/), September 18-20, Prague, Czech Republic Sign up for news about Developer Portals & API documentation Subscribe *We will not publish, share, or sell your email address in any way. - [Sign up to our newsletter](http://bit.ly/devportals)