Stay updated
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,800+ subscribers. (See email archive here.)

Search results

Podcast: API Design and Usability with Arnaud Lauret (API Handyman)

by Tom Johnson on Dec 7, 2019 •
categories: api-doc • podcasts • technical-writing • apidoc-site-updates

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 here:

You can download the MP3 file, subscribe in iTunes, Google Podcasts, or other podcast platforms.

The Design of Web APIs, by Arnaud Lauret

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

Resources

Buy me a coffeeBuy me a coffee
Stay current with the latest in tech comm
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,800+ subscribers. (See email archive here.)

Share
follow us in feedly

About Tom Johnson

Tom Johnson

I'm a technical writer / API doc specialist based in the Seattle area. In this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, visual communication, information architecture, writing techniques, plain language, tech comm careers, and more. Check out simplifying complexity and API documentation for some deep dives into these topics. If you're a technical writer and want to keep on top of the latest trends in the field, be sure to subscribe to email updates. You can also learn more about me or contact me.

Comments