Adobe FrameMaker

Get new posts delivered straight to your inbox.

Subscriber count: 4,300

Stitcher radio

Adobe FrameMaker

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

Jan 19, 2018 • writing

I recently gave a presentation called "Publishing tools for API documentation" to the Write the Docs South Bay meetup group on January 18, 2018. The location for the meetup was Google's Mountain View campus.

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.

follow us in feedly


Get new posts delivered straight to your inbox.

Subscriber count: 4,300

About Tom Johnson

Tom Johnson

I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include the following technical communication topics: Swagger, agile, trends, learning, plain language, quick reference guides, tech comm careers, and certificate programs. I'm interested in information design, API documentation, visual communication, information architecture and findability, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here. You can also contact me with questions.