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

Search results

API doc course update: Re-architecting the OpenAPI spec tutorials to start with visual modeling tools first, then code

by Tom Johnson on Apr 28, 2020 •
categories: api-doc apidoc-site-updates

One of the most challenging aspects of my API documentation course is with the OpenAPI specification. Describing how to code this detailed spec line-by-line is not only tedious but highly prone to error, confusion, and frustration. Recently, I decided to shift the approach in my course to begin first with coding the OpenAPI spec in a visual editor using Stoplight Studio, and then later, if desired, transition to a code-based approach.

The new flow in the OpenAPI section looks like this:

As part of this new flow, I added an extensive Stoplight tutorial here: Create an OpenAPI specification document using Stoplight Studio’s visual editor.

I think this new approach (visual first, then code) makes more sense for several reasons. Not only is this a walk-before-you-run type of approach, but the reality is that if your head isn’t buried all day in the OpenAPI spec, it’s hard to remember all the specification details. I work much more frequently with library-based APIs, mostly Android, than with REST APIs. When I shift back into REST API mode, I have to refresh my memory about many things.

My guess is that in several years, using a visual editor will be the norm anyway. Sure, some systems (like Linux) that let you operate entirely from the command line appeal to some people, but the visual manipulation of objects (e.g., Windows interfaces) turns out to be much more user-friendly and easy, and the easy model tends to win out.

Sponsored content

To make another comparison, at home my family keeps re-adjusting our family chore chart, and during the last go-around, I asked my 15-year-old which approach she would prefer. Her immediate response: “Whatever requires less work.” This is pretty much how most of us operate. Users will do whatever requires less work, if that means poking around in the UI to figure it out instead of reading the longwinded user guide, or copying and pasting a code sample from Stack Overflow to see if it works, and then if it doesn’t, copying and pasting some other sample until it does, or cloning a sample app and just customizing it a bit for our needs, and so on.

When it comes to creating the OpenAPI spec, if you can generate out most of what you need using a visual editor in under an hour, isn’t that approach going to succeed over one that requires two weeks of careful study of the code? The latter might be more beneficial in the long run, but we rarely operate in this mode, especially if in the long run we might not even be working on REST APIs.

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. 6,100+ subscribers. (See email archive here.)

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.