I keep writing and publishing posts about (REST) API related matters, when I keep thinking that I have more to say about The Whole World of Software Documentation. Some day I’ll figure out why. In the meantime:

I’ll start with a word-related peeve. Or, more precisely, a definition-related peeve. It also happens to be documentation-related.

Swagger is not a documentation tool.

Got that, writers who are presumably the guardians of vocabulary and meaning and precision and usefulness?

I’ve lost track of how many times I’ve seen this error repeated. I am not the only one to call it out — see, notably and more authoritatively, Kin Lane’s related post — but I am the only writer I know to do so.

Why does it matter? After all, you can do some things with Swagger to produce documentation, so why not call it a tool?

Because in fact it is something else. It’s a specification. And the difference matters a lot when it comes to producing either (a) documentation or (b) the multitude of other useful tools that Swagger is inspiring these days.

In fact, as I write, I realize more clearly than I have before just how much reducing the definition of Swagger (not to be confused with a “Swagger definition”) to a mere documentation tool does a great disservice to everyone who’s not already involved in the nascent space of API development. And even to some of those who are already so involved. It also does a disservice to those writers who don’t know any better, but who are approaching the world of API documentation for the first time and who might understandably be confused when they discover that no, Swagger doesn’t work like doxygen. Not even close. Swagger-UI doesn’t even work like doxygen. And again, not even close. Depending on your development environment, you may be in for a very rude shock if you start from this assumption (whether you’re a developer or a writer).

Naming things is notoriously difficult in software development. Mis-using or redefining words already in common and valid use *in the world of software development* only makes things more difficult. (Appropriating perfectly good words already in general use for very specific and unintuitive meanings in software contexts is a peeve I’ll save for another day.) This word person at least is trying to do her part to set the record straight for at least one term and its (software-related) meaning.

p.s. After I wrote the preceding, but before I published it, I learned that the Silicon Valley chapter of the STC has scheduled this meeting, which represents a move in the right direction. It focuses on RAML, not on Swagger, but in the context of my screed here that’s a minor detail.