Zen And The Art Of Automanually Creating API Documentation - An Inquiry Into Process¶
Description
When presenting an API to a customer, that customer's developers depend on accurate and clear API documentation to understand the API contract that their code will interact with. How do we make that documentation accurately represent behavior, and also look good? How can we handle APIs spread across multiple microservices and teams in a company, and make the documentation all look consistent instead of looking like none of the teams have ever talked to each other?
Plenty of tools already exist for developers to write code that documents itself and creates its own OpenAPI spec files. However, developer teams do not always have the technical writing background needed to adequately describe APIs for customer use. Technical writers can make excellent customer-facing documentation, but being isolated from development and trying to keep up with field definition changes, behavior changes, and various breaking changes, is an onerous task. And how do we make it work with legacy code?
This presentation will show how we are pulling all of this together and creating a new process for creating API documentation that we can be proud of. It will show how we are creating a partially automatic, partially manual process that is fault-tolerant and flexible enough to handle differences in technical approaches, customer needs, and personalities.
What questions will this talk answer?
- How do I make a whole bunch of different services look uniform and coherent?
- How do I create a process for creating OpenAPI spec files that are presentable to customers?
- How do I get technical writers, developers, and managers all working together?
- How do I convince people that API documentation is a priority for everyone, not just technical writers?
And what can we learn from 24 hour psytrance at Burning Man that will help people work together, anyway?
- Conference: Write the Docs Portland
- Year: 2023
