I’ve been trying to understand my own uncomfortable reaction to a lot of discussions about software documentation. To most of them, in fact.

I write documentation for a living, and I find the challenge of writing good docs pretty compelling. So why do I squirm and feel like running away every time someone I follow on Twitter posts a link to another resource about documentation? Why do I try to avoid most of the standard resources in my chosen field of endeavor? I don’t mind telling people what I do, and like many folks who care about good docs, I am in love with the Write The Docs conferences. So what gives?

Part of the answer lies, I think, in the title of this post. It’s also part of the answer to why I was uncomfortable for so long with the idea of even starting a blog (and why I’ve malingered over really getting it going).

As I see it, writing documentation is a thing you do, not a thing you discuss in the abstract. Or if you discuss it outside the context of a particular deliverable, you do so in immediately practical ways: what’s the most appropriate way to call out a particular kind of UI element (or should you even call it out)? How should programmers and writers jointly contribute to Javadoc comments? What are some good ways to organize a programming guide/a user manual/a knowledge base? What does this error in my doc build mean and how can I fix it? What’s the best way to support localization?

These aren’t, obviously, the only sorts of documentation questions people are interested in, or even the only sorts of doc question I care about. But more abstract discussions often very quickly move into generalizations about Documentation As A Self-Evident Truth, and that’s where I think my discomfort starts. This is what I’m calling “fetishizing.” Documentation Matters, doncha know. Good Documentation Can Save The World.

And There Is One Right Way. Thou shalt write according to the dictates of “structured authoring” — a term that continues to bewilder me, even though I work within the constraints of some of its dictates. What does “unstructured” authoring look like? And does anybody really “author” software documentation? (I sure hope not …) Or thou shalt “single-source” — a term whose practical meaning has looked pretty slippery to me over the years. Or use a particular toolset/platform/workflow. Or not. (Just ask a group of folks who write about “agile” …)

Context. Context is what fetishized documentation discussions lack. If your doc content, however it’s organized, however it’s presented, gets the job of helping your users get their jobs done, that’s what matters. Sure, there are ways of thinking about and organizing docs that can help you achieve this goal. But ultimately it’s your product and your users who matter, not the theorizing of folks who are overly invested in whatever the latest doc trend might be. And maybe it’s ultimately that lack of context that makes me uneasy when doc discussions go all abstract. All the carefully chosen stories or examples that prove the abstract point can’t make up for the fact that somebody else’s abstraction does not take your context into account.

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.

I didn’t mean to dive into this kind of topic so early in this blog’s history, but then it just sort of happened. This post is much later than I planned, some things happened at work, and I just talked about tools for REST API documentation at a recent WriteTheDocsPDX meetup. So related issues have been on my mind for a while.

APIs need writers. And not just for documentation. Let me explain.

Earlier this year, I came across a talk at GlueCon titled “Why Your Next API Should Be Designed By a Linguist,” by Rebecca Standig of keen.io. I still have not read or listened to the whole talk, but the title alone stuck with me, and keeps coming back to haunt me. There’s a lot more to Rebecca’s argument than the kind of thing that I talk about here, but it’s part of the inspiration for this post.

I’m talking about REST APIs here, but the same points apply to any sort of programming interface. Or any sort of interface, period: CLI, GUI — ultimately they all come up against the issue of usability, or user experience. The importance of usability and user experience varies, of course, from interface to interface — who are its consumers, how can it be explained, how can information be exchanged across it.

As it happens, my first experience with usability as it relates to programming interfaces wasn’t with regard to REST, and I didn’t really know much about programming at the time. I was a mere editor of programmer documentation for a well-known platform that I won’t name here. A new version was under development, and the writer handed off a draft of the docs to me for review.

I sent back a redesign of the APIs — although at the time I didn’t quite realize that was what I was doing. But I offered a reorganization — what writers call a developmental edit — and some renaming suggestions. As I recall, it was difficult to figure out just what was supposed to happen when, and I thought that changing about some of the words could help.

It did. I wound up in a room with the writer and one of the architects for the project, and the APIs were redesigned according to my suggestions. (I prefer to think that the fact that the project never saw the light of day was unrelated to my proffered redesign.)

Fast forward several years. I’m now responsible for documenting two sets of REST APIs, one of which is planned from the start for external consumption. The other has grown out of a larger project to rewrite an entire large enterprise server product with REST APIs to support the GUI. At least, supporting the GUI was the original intent — but as I’ve been able to piece together the story, somewhere along the way the product manager thought, hey, our external customers could use these APIs too, and we could provide a much-requested enhancement to enable customized scripting against the server. (This is an on-premise server, not a public one.)

The trouble is, as we all know by now, APIs that are designed and written for internal consumption do not always match the needs of external customers, and vice versa. The reasons for the mismatch are many, and vary from API to API. Here’s what I’ve seen, though, that a writer can help with:

  • Clear, consistent, sensible naming. Why inflict an endpoint called /foo_queue on any consumer of the endpoint, when /foos complies better with REST standards and doesn’t lead the customer to wonder “why a queue?”
  • The analysis that leads to clear naming can also contribute to API design. Naming is potentially complicated if the resource in question is a server object. Often the client is really most interested in the object behavior, which can make it tricky to name the resource in a way that indicates both what the client/customer can expect and at the same time comply with REST standards, wherein resources are always nouns. But if you look at the problem in this way, you can also turn it on its head. (And here I suspect I may be getting a little closer to what Rebecca is talking about with respect to the intersections between linguistics and software programming.) How you design the server object itself — how you create its grammar and syntax — is deeply affected by how you think about the words you use to describe and name its components. There’s a lot more to say about this issue, but I’ll save it for another post. The main point here is that people whose job it is to describe things in words can help understand how to make the things that the words describe.
  • Coherent organization. At a software design level, this is obviously related to the previous point, but I’m trying to stick to the writer part. We organize doc content around customer jobs — tasks, workflows, and supporting overview/conceptual and reference topics where applicable. This organization applies to any kind of doc, for a GUI-based product or for an API, with the caveat that the API docs are dominated by code examples, which show your developer customer what to do (instead of just telling them). But you also need reference docs, and they are harder to manage if you haven’t laid out your APIs in a thoughtful consumable order, especially if you’re generating docs from your code annotations/comments/docstrings.

Some product teams that develop APIs explicitly include writers as part of the core team. I worked this way briefly, and my co-presenter at WriteTheDocsPDX does now, at Salesforce.com. It’s good for the docs, obviously, but it’s also good for the product — the APIs themselves.

This blog, and the bigger website it wants to grow into, is a long time coming. For years I actively avoided the idea of a blog, lacking any sense of a clear purpose for such a project, and not caring to add to the general noise of the interwebs. Almost a year ago, that attitude started to change. I didn’t do anything else differently, I just started to realize that I did have something of my own to contribute to the professional discussions I’d been following fitfully for years. I also started to dream bigger about my professional goals.

I had grandiose notions of creating a built-entirely-by-my-very-own-self website using cool cutting edge (or at least fashionable) tools, showing off what I could do behind the scenes as well as with the words on the page.

Yeah, right. I still have those notions, but I’m also still working on turning them into realistic plans — quite a different proposition.

Then I attended a conference, my first professional conference ever in my second career (or third, or fourth, depending on how you count) — mildly ironic, since my first professional career involved a very large amount of conference-hopping. And … it was GREAT. Inspiring. I had even more to say, and groups of people I hoped to be able to discuss my thoughts with.

That conference was writethedocs PDX, back in early May. It’s now mid-September. And … yeah, it’s just a blog. On WordPress. No exploring new tech yet (new to me, that is). But maybe someday it will grow into some semblance of the site I originally envisioned. Or maybe it will morph into something altogether else along the way.

In case you find this page early on in the bloglife, and also to try to keep myself honest, here are some current potential topics, in no particular order:

  • Doc quality — how to test, assess, measure ROI
  • (Closely related) How do we define good software doc writing?
  • User research — how can we know which docs really matter? What customers really need?
  • OAuth and me
  • Swagger and me
  • APIs and me (mostly docs)
  • Learning to code on my own