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.

Maybe inspiration will stick this time. I hope. I will also never put the word “procrastination” in a title again. Proleptic, much?

More than a year ago I was inspired to start what became this blog. It took me half a year to get the thing up and running, and more than six months since my last published post, I’m only now getting around to blog post #3 (although in my defense I would like to state that half a dozen or so posts languish in draft state).

I have Real Things I want to write about, but I also feel the need to provide some kind of interim narrative. I’m not sure who I’m writing for — myself, as I think is obvious, but the existence of this blog means that I’m also writing for other people. I suspect that I need to stop worrying about this question of audience, though, because it’s one reason why it’s so hard for me to actually click that not-too-big blue Publish button.

The other reasons have to do with my background. First of all, I write for a living. I do not call myself a writer, however, because I do not have a passion for the activity we call writing. I like to explain things that I’m interested in, which is why I’m willing to call myself a technical writer (or “documentarian” — but more on that term in a later post). And one big set of things that I’m interested in have to do with what I’m paid to write about, namely a lot of stuff that’s related to software development.

So as someone who produces text professionally, I fuss about words. I’m paid to fuss about words. I choose to be thus paid because it appears that I fuss about words compulsively, and with a reasonable degree of what passes for competence in the current state of the English language.

I’m also an academic refugee, who spent decades of her life writing things that required her to produce data from which she derived her conclusions — or at the very least, References that could provide the Authority from which Conclusions Could Be Derived. In other words, I always had to prove my point. Show AND tell. Always be prepared to back up your assertions.

This background contributes to my apparent success as a producer of software documentation — TL;DR version: I’m a highly trained researcher. Ask me to write about something, and I will go find out about it. My work-related reading list is, shall we say, eclectic. (Currently open tabs are related to OAuth, OpenStack, content reuse, lots about API design, Python, Javascript frameworks, asciidoctor, systems analysis, the history of technical writing — and cocktails. Maybe that last one is only indirectly related to work.)

But ask me to write about stuff “just because” I’m interested in it, or care about it? Yes, I set myself up for it, but it’s proving far more daunting than I expected. I have to stop the compulsion to prove every point I want to make, to try to tell The Authoritative Story, to be The Expert.

When I put it like that, I think “ick,” in fact. That’s the antithesis of what I want to do here. I want to tell my stories, give my perspective, honor those who have inspired me but not lay upon them the heavy mantle of Authority. If I’m lucky, I’ll get to have conversations with the folks who eventually find their way here. And even if I’m not lucky in quite that way, I’ll have committed some of my ideas to a more permanent medium than the fitfully firing synapses in my own brain.