Write the Docs South Bay: Publishing tools for API documentation

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 ( tom@idratherbewriting.com ) 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.