Documenting APIs
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 is on! Great inspirational kick-off by @jystewart #writethedocs
— Kristof Van Tomme (@kvantomme) March 4, 2016
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:
Great insights about API docs, not only for government use by @RosalieMarshall #GDSapidocs #writethedocs pic.twitter.com/v9OvDIX2gc
— Kristof Van Tomme (@kvantomme) March 4, 2016
#GDSapidocs Government as a Platform:
— Roger Sheen (@infotexture) March 4, 2016
“We don't want to be building a kitchen every time we need to have a meal.”https://t.co/eP5VsoRnnB
Great talk on researching who the users of API docs are, and what they want, from @RosalieMarshall of GDS. #GDSapidocs
— Beth Aitman (@baitman) March 4, 2016
Emerging trend from @RosalieMarshall and @ellispratt talk at #GDSapidocs #writethedocs event is that we need better tools for API docs...
— Kristof Van Tomme (@kvantomme) March 4, 2016
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:
Difference in skills required for technical authors and API writers @ellispratt #GDSapidocs #writethedocs pic.twitter.com/zX6t6IF9ci
— Kristof Van Tomme (@kvantomme) March 4, 2016
API docs are a team responsibility. Make them part of the team's review process - same tools @ellispratt #GDSapidocs pic.twitter.com/NrBvw0VL98
— Beth Aitman (@baitman) March 4, 2016
At #GDSapidocs, @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
There might be a legal requirement to have API docs in non-English languages @ellispratt #GDSapidocs #writethedocs
— Kristof Van Tomme (@kvantomme) March 4, 2016
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:
API docs are not just for developers, managers are reading them now also @ChristianVogel_ #GDSapidocs #writethedocs pic.twitter.com/z2OvUY9xRd
— Kristof Van Tomme (@kvantomme) March 4, 2016
At #GDSapidocs, @ChristianVogel_ on RAML for single-sourcing API docs:
— Roger Sheen (@infotexture) March 4, 2016
“Write once. Use many. Creative laziness encouraged.”#writethedocs
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.
Trying you get technical writers involved into the Open API initiative @olensmar #GDSapidocs #writethedocs pic.twitter.com/DY6HG9N9X2
— Kristof Van Tomme (@kvantomme) March 4, 2016
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:
@baitman Also the first public release of Swaggerly is on it's way. Used to build https://t.co/JHPDuzZGbv #GDSapidocs
— Chris Smith (@zxchris) March 4, 2016
@baitman I had such a good response from the talk... clearly time to publish my 8-factor api design guide! Soon! #GDSapidocs
— Chris Smith (@zxchris) March 4, 2016
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:
API blueprint overview by @kylefuller #writethedocs #gdsapidocs pic.twitter.com/rBpJJpt81l
— Kristof Van Tomme (@kvantomme) March 4, 2016
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:
Interactive docs and quick API onboarding experiences drive adoption. @KimStebel #gdsapidocs #writethedocs pic.twitter.com/fdhAqpngM3
— Kristof Van Tomme (@kvantomme) March 4, 2016
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:
DITA to @GitBookIO transformation demo by @infotexture at #GDSapidocs #writethedocs pic.twitter.com/cBlWk6qOSb
— Kristof Van Tomme (@kvantomme) March 4, 2016
Automated publication flows can be a challenge for people not used to them @infotexture #GDSapidocs #writethedocs pic.twitter.com/AdxaS8i9ux
— Kristof Van Tomme (@kvantomme) March 4, 2016
Why choose between DITA and markdown if you can have both? @infotexture #GDSapidocs #writethedocs
— Kristof Van Tomme (@kvantomme) March 4, 2016
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