Three Terms API Documentation Writers Should Never Misuse
By Robert Delwood, a Lead API Documentation Writer
“Words mean things and technical words mean technical things.”
This should be the mantra of every technical writer. And yet, technical writers, the very people trained and paid to be clear, are often the cause of misunderstanding. The following terms have precise meanings in the technical community, so attention is needed to use them correctly.
“Swagger”
Don’t call it Swagger. It’s not. I don’t know how that name became so ubiquitous. People who don’t even know what Swagger is, call it Swagger. It’s OpenAPI.
Swagger is a trademark of SmartBear, and is actually a suite of tools. It is apart from, and distinct from, OpenAPI. The connection is that in 2010, SmartBear created a structured file for use with REST APIs and named it Swagger. It was popular and in 2015, they donated it to the community and renamed it OpenAPI. With that donation, both are independent of each other. OpenAPI has its own spec (https://www.openapis.org/), is on version 3.1, and continues to expand. Swagger as an API source is no longer supported and will end in version 2. That means the two are diverging. The specs are different and third party tools will only support OpenAPI going forward.
“API”
The term API refers to a collection of related requests. A request is an individual endpoint within a collection. The two terms are not interchangeable. Think of it this way: API is to request, as book is to page. You would never say My favorite book is page 12.
“API Documentation Writer”
Many shorten this title to the simpler API writer. But that is misleading if not outright wrong. An API writer is a developer who codes the functions of an API and requests. It is a development function. An API documentation writer is someone who writes API documentation. This is technical writing function. If you don’t believe there is a difference, do an Internet search for API writer jobs to see what happens.
Conclusion
There is no good defense for misusing these terms. The common comeback is that the audience “will know” what we’re talking about. This is wholly inappropriate, and, to be blunt, an ignorant response. No technical writer today will defend an ambiguous position with “they’ll just know.”
An example of using the wrong term is calling your smart device a cordless phone. The audience may know what you’re talking about, yes, but that’s not the point. Some will likely take a moment to figure out what you mean, and others may even ask for clarification: “Do you mean my wireless phone?” By calling it the wrong or an imprecise term, the technical writer did two things:
· Caused confusion, the very thing they’re paid not to do.
· Made themselves look bad. This takes away credibility.
And it’s needless. There is already a commonly understood and exactly precise term available: Wireless phone. You may even be able to get away with just phone. Instead, the speaker has gone out of their way to use the wrong term. In talking about API documentation writing, technical writers have entered the developer’s world and we are obligated to use the correct, precise terms.