Input needed:
I'm gathering data about trends in developer documentation for 2020. If you write docs for developers, please take this survey. (You can view the ongoing results here.)Podcast: API Design and Usability with Arnaud Lauret (API Handyman)
Arnaud Lauret, also known as the API Handyman, recently published a book called The Design of Web APIs. In this podcast, I chat with Arnaud about his book, specifically exploring best practices for designing web APIs and focusing on the roles technical writers can play.
Listen to this post:
You can download the MP3 file, subscribe in iTunes, or listen with Stitcher.
Podcast topics
Here are some of the API design/usability topics we chat about in the podcast:
- What API usability is, and how usability is the same/different with developer tools
- How writing documentation tests the usability of a product
- What tech writers should look for to know whether an API is designed well
- What to call each of the components in an API (e.g., whether the term “endpoint” should be used)
- How tech writers can influence design and usability when they’re so far downstream in the development process
- Best practices for creating tutorials on API doc sites
- Spec-first design versus auto-generating the OpenAPI from the code
- Which framework you would you choose to work with to render the API spec
- Whether we’ll eventually move into a state where manually editing the OpenAPI spec code by hand becomes antiquated
- The Open Map visual diagram that shows the OpenAPI structure
- Recommended APIs that we should learn from and why
- Why providing the OpenAPI spec is important even if you don’t generate your docs from it
- How tech writers might interact with their company’s API style/design guide and why
- Whether the reference content and user guide should be separate or seamless
Tip: If you'd like to explore these ideas in more depth, consider getting a copy of The Design of Web APIs. I've read the book and found it relevant and helpful to the work of technical documentation.
Resources
- The Design of Web APIs (book)
- API style book
- OpenAPI Map
- API Handyman blog
- @apihandyman (Twitter)
- API Developer Weekly newsletter
- WebAPI Events
- DBS Developer Portal
- Visual Code Studio
- Swagger Viewer extension
- openapi-lint extension
