Recording of WTD South Bay presentation: Publishing tools for API documentation
Slides
Here are the slides:
Audio
Listen here:
You can download the MP3 file, subscribe in iTunes, or listen with Stitcher.
Video
Event Description
The description is as follows:
Publishing tools for API documentation
In developer documentation spaces, technical writers often employ more developer-centric tools to author and publish documentation. These developer-centric tools usually involve treating documentation like code – this means managing the content with git workflows, using open-source tooling such as static site generators, formatting the content in Markdown, building from the server, and so on.
Additionally, when documenting REST APIs, many documentarians use standards such as the OpenAPI specification to describe the API. Various tools, such as Swagger UI, can read the OpenAPI specification and generate interactive documentation that lets users try out the endpoints directly in the browser. Integrating Swagger UI’s output with the rest of the documentation can be challenging, but many doc sites do it seamlessly.
In this presentation, we’ll explore this landscape of authoring and publishing tooling in the API documentation space. Some questions we’ll explore involve the following:
- Why do API documentation projects often abandon traditional help authoring tools?
- What unique needs do API technical writers have?
- What are some pros and cons of the docs-as-code approach?
- What are some common tools and workflows used by API documentation groups?
- What challenges are inherent in these docs-as-code tools, particularly with search, localization, and validation?
- What approaches are writers taking to merge structured authoring techniques with the more open, unstructured docs-as-code techniques?
For details, see the event description on the WTD San Francisco meetup group: Publishing tools for API documentation.
Location and other details
The meetup was held at the Google campus in Mountain View. Details are on the meetup event details.
Date: Jan 18, 2018
Time: 6:30-8:30pm
Location: Google Building 1310, 1310 Shorebird Way, Mountain View, CA
Cost: Free but you must RSVP through meetup.com.
This was the first “South Bay” meeting for the WTD San Francisco group. South Bay includes pretty much everywhere from Redwood City down to Morgan Hill.
Other API doc presentations
I’m giving a few API doc presentations this year. They won’t all be the same presentation. Instead, I’m covering different sections in my API documentation course.
Whereas the STC Silicon Valley presentation covered the Intro to API documentation section, Using a REST API like a developer, and Documenting API reference sections, the WTD South Bay chapter covered the Publishing your API documentation section. Of course, given the limited time, the presentations only cover these sections in a cursory way.
For other presentations scheduled in 2018, see my Presentations page.
