This is a post for beginners. Specifically, it’s a post for technical writers (regardless of specific job title) who want to learn more about API documentation, a realm traditionally separated from other forms of software documentation, and often made mysterious by folks who don’t use it or make it.

That I find this post necessary says quite a lot about the state of software documentation and the technical writers who produce much of it, but that’s a point I’ll explore in more detail another day. For the time being, I want to offer advice that’s meant to complement what other technical writers have said or written on the subject.

Here’s the why of my advice, which is bigger than just API documentation. In case you hadn’t noticed (and it seems that this particular rearguard action is still being fought), the new (or renewed) world of software documentation is moving rapidly toward a world that no longer isolates writers in their own little silos with their own proprietary tools and workflows to which no one else has access. This is particularly true for developer documentation, of which API docs are (partly) a subset. So if you haven’t done it already, you need to start thinking of yourself as part of a product development team, not (just) as part of a documentation team. You are writing with and for product teams, and especially for product managers and developers. Which means you need to turn yourself into as much of a PM/dev as you possible can.

So, try shifting focus. Stop reading about “API documentation.” At least for a while. And start reading about APIs. Specifically, read about REST, because that’s what almost everyone means by “API” these days.

(As I write, the one highly visible exception to the mainstream equation of “API” with “REST” is the Oracle v Google case. But the high level issues around what an API is are still the same — they are all interfaces, surfaces that other things can connect to without knowing what’s underneath the surface. And indeed, they should not know.)

Try some of these suggestions:

• Read API and developer blogs, and read up on the major API management platforms. Yes, these are commercial ventures, but the folks who have built them have invested a lot in educating communities about APIs and in providing great information that any aspiring API documentarian should be familiar with. Here are just a few of my favorite resources. This list is not comprehensive — explore on your own and come up with your own set of tabs and bookmarks of similar material.
  • The Nordic APIs blog
  • Matthew Reinbold’s REST API Notes, his website, and his listing of API events. (Matthew is a colleague and I’m very fortunate to be working with him. Read his stuff, and anything he recommends.)
  • James Higginbotham’s site. Also, sign up for API Developer Weekly,the newsletter that he puts out with Keith Casey
  • Kin Lane’s API Evangelist site (start with the blog, and then explore further)
  • Programmable Web. It’s a lot about the business side of APIs, but you need that, too.
  • (Not for the faint of heart) The words that started it all, Roy Fielding’s dissertation (although as Fielding continues to point out, REST is really just how the web works. Or ought to work.)
• (shameless plug) I said not to read me, but I mention a few other good resources (tools, folks to follow on twitter) in this interview with Jennifer Riggins on APIEconomist.
• Attend local API meetups.
• Learn about OAuth 2.0 (and about the controversies surrounding it). I mean really learn — read the spec, and read a lot of different docs (about different implementations — everybody implements OAuth in their own way, because it’s not a tool, it’s a specification).
  • OAuth 2 spec
• Learn about API security — properly speaking about web security more generally. Learn about certificate stores, and encryption. This, with OAuth, is an area that far too few folks pay sufficient attention to, and it badly needs the help of good documentarians who can help developers understand its importance and show them good security solutions.

Remember that the developers who are the audience for API documentation are users, too. Developer Experience (DX) is your new UX. As you learn more about APIs, you’ll learn about good API design, and this is tremendously important. As with any other interface, if you’re having a hard time documenting an API, and the docs are getting complex and convoluted as you chase down tangled details, chances are the API could use a good redesign. Catch these issues, as you would poorly worded GUI text or a badly laid out GUI, and you’ll make life easier for everyone. (You’ll also help evangelize the role of writer as a key member of the product dev team while you’re at it.)

I’ll post a separate list of my favorite discussions about API documentation.

 

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.

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.