API doc course update: Re-architecting the OpenAPI spec tutorials to start with visual modeling tools first, then code
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.
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.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.