Lorna Jane Mitchell (Redocly): OpenAPI for Documentarians

This talk was presented at the API The Docs Amsterdam 2023 conference on 6-7 June. We are glad to present the video recording and the talk summary.

Visit the talk listing page for an overview of all presentations!

Lorna Mitchell

VP of Developer Experience at Redocly

Lorna's presentation (video recording)

"Establish and maintain documentation standards to ensure API consistency and usability."

In this demo, you can hear about:

• The significance of Open API: the importance of Open API as a standard way to describe APIs is emphasized, highlighting its wide adoption and open nature that allows for community input and influence.
• Understanding the structure: the breakdown of the structure of Open API documents (explaining key elements like versioning, info blocks, security, and tags) provides a clear map for navigating through API documentation.
• Tooling for documentation: various tools available for working with Open API are discussed, underlining the need to choose the right tool for your team's specific needs and workflow.
• Standards and governance: it is essential to establish documentation standards within your organization and integrating documentation generation into the development workflow.
• Acknowledging the value of documentation: documentarians play a pivotal role in enhancing the developer experience.

Takeaways

• Documentation matters: even in startup environments, robust documentation is crucial for transparency, investor relations, and overall success.
• Technical writers are essential: dedicated technical writers ensure the quality of documentation, even when working with highly skilled developers.
• Hiring wisely: consider bringing in experienced technical writers or seeking external expertise when forming a technical writing team.
• Streamlining with automation: building an internal developer portal using automation tools can streamline and enhance documentation efforts.
• Establishing reputation: creating tech-related content like blogs can help establish your organization as tech-centric and reputable.