The Four Stages of OpenAPI¶
Description
For API documentation, you made the decision to move to OpenAPI. OpenAPI is a remarkable specification and framework. It became the industry standard in 2016. This standard provides API documentation with structure, consistency, and versatility. This is an important milestone in that it moves API documentation away from Word files, PDFs, and other unstructured formats.
However, making that decision is only the initial step on a longer journey:
- New documentation, API documentation writers
- Documentation only, API documentation writers and developers
- Prototyping, API documentation writers, and program managers
- API-First, API documentation writers, and developers
The complexity increases as you go down the list as do the rewards. The product gets more mature, and the team, more experienced. Each stage has its own set of challenges and different team members supporting it. The other realization is that API documentation is no longer a writer-only endeavor. It takes a team.
In this presentation, I will share these four stages. This helps you understand the project in a long-term view. It also enables you manage to expectations when getting started. I discuss:
- Why you want to follow this progression,
- What each stage means,
- What the expectations are.
You don’t have to already be an API documentation writer. You may be interested or new to the field and want to know more. Neither do you have to know programming or a specific programming language to begin. As long as writers treat this as a craft, the documentation will seem to write itself.
- Conference: Write the Docs Portland
- Year: 2024
