Adobe DITA World
Stay current with the latest in tech comm
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 4,500+ subscribers

Stitcher radio

Search results

Adobe DITA World

Recording of WTD South Bay presentation: Publishing tools for API documentation

by Tom Johnson on Jan 19, 2018
categories: api-docpodcastsstitcher

I recently gave a presentation called "Publishing tools for API documentation" to the Write the Docs South Bay meetup group on January 18, 2018. You can view a recording of the presentation, browse the slides, and listen to the audio here.

Slides

Here are the slides:

Publishing API documentation

Audio

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.

Stay current with the latest in tech comm
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 4,500+ subscribers

follow us in feedly