Write the Docs South Bay: Publishing tools for API documentation

Write the Docs Bay Area
Write the Docs Bay Area
Public group

Google Building 1310

1310 Shorebird Way · Mountain View, CA

How to find us

Use the front entrance to 1310 Shorebird Way in Mountain View. One of us will be there to let you in. Plenty of parking right in front of the building and across the street. The meeting room (Esalen) is on the left side of the building.

Location image of event venue


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?

About the presenter

Tom Johnson ( [masked] ) works as a technical writer for Amazon in Sunnyvale, California. He writes a blog called idratherbewriting.com (http://idratherbewriting.com/) and is working on a book about API documentation.