Why Your APIs Need Writers

It might not be what you think

I first wrote about this topic more than two years ago for my personal blog. A year later, I presented on this content at APIStrat Austin 2015. Now the topic is even more timely than when I originally addressed it.

The fact that technical writers are an important resource for documentation appears to still be news — popping up in some surprising contexts. In the past few months, I’ve seen two separate public statements of surprise that technical writers even existed — one of them at a software documentation conference, and another at an API conference. Clearly the word still needs to be spread.

Your API needs a technical writer, and not just for documentation.

Many people talk and write about the importance of documentation for the success of an API, specifically REST APIs. Some of these people are technical writers; some, perhaps most, are programmers or product managers or evangelists. They’re correct, of course, good documentation is vital to a good API. But the story does not end with the docs. It only starts there.

Why Writers?

While my focus here is specifically on REST APIs, the same points apply to any sort of interface: programming interfaces, CLI, GUI — ultimately they all come up against the issue of usability, or user experience. The details of usability and user experience vary, of course, from interface to interface — who are its consumers, how can it be explained, how can information be exchanged across it? But its importance does not vary.

As it happens, my first experience with usability as it relates to programming interfaces wasn’t with REST. In fact, I didn’t really know much about programming at the time; I was an editor of programmer documentation. A new version of a set of APIs was under development and the writer handed off a draft of the docs 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. I offered a reorganization — what some 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 in the APIs and I thought that changing some of the wording 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 didn’t set out to redesign the APIs. I set out to explain them. When explaining got difficult, though, I did what I’ve always done when explaining an interface of any sort gets difficult — I went to the writer, and from there to the product team, to ask “Why?” and “Couldn’t we change these words to help the user better?” And it turned out that those were the right questions.

Writers ask these questions of software all the time. We ask them of APIs. And in answering writer questions, an API team can design and implement a better API. To explain at a somewhat higher level, here’s what a writer can contribute to your API:

Coherent Organization

Writers 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 both a GUI-based product or for an API — with the caveat that the API docs are dominated by code examples, which show your customer what to do (instead of just telling them). But you also need reference docs, and these are harder to manage if you haven’t laid out your APIs in a thoughtful,l consumable order. Especially if you’re generating docs from your code annotations/comments/docstrings.

So looking at doc organization early in the API development cycle can help identify issues with the API itself. Ideally address these issues at the level of design.

Clear, Consistent, Sensible Naming

Why inflict an endpoint called /foo_queue on consumers of the endpoint? Especially when /foos complies better with REST standards and doesn’t lead the customer to wonder “why a queue?”

Writers are by definition word people. We often catch naming issues before anyone else — and when the naming issues are fully addressed, larger design issues often get better resolved too. Writers are also often the first advocates for internal or external customers of your API — for the folks who need the clear descriptive names to help them understand what your API does and how they might use it.

The Same Analysis That Leads to Clear Naming Can Also Contribute to Better General API Design

Naming is inevitably more complicated if the resource in question is a complex server object (setting aside the question of whether such objects should be served as resources in the first place). Often the client is really most interested in the object behavior (that is, the verbs that tell the client what they can do). This can make it tricky to name resources in a way that indicates what the client/customer can expect while complying with REST standards wherein resources are expected to be nouns.

An example I’ve encountered in contexts ranging from enterprise security to identity management is where the server returns data that’s derived from its communication with another application. This additional app may or may not communicate directly with the API client, and it’s often providing event-driven data. “Why does the API client need this data?” and “What can the client do with the data?” are writerly questions that the documentation must address; but as often as not, when you start answering them, you find that the API works better if it serves different event data, less data, or (rarely) more data.

More generally, 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. People whose job it is to describe things in words can help you understand how to make the things that the words describe.

Writers On Your Team

Some product teams that develop APIs explicitly include writers as part of the core team and these teams tend to produce better API products. More teams should follow their lead. Writers can provide a very special kind of QA for APIs, especially at the design phase. We focus on language to convey meaning — to describe what an API does. But our focus on the audience for APIs and their documentation means that we also focus on the ways that language is understood by developer users — to describe what the API can do for them. We can contribute invaluable perspectives on usability for the API consumer — when often the rest of the team tends to focus on the API producer. Everyone on an API team wants to create a good product; let your writers help make that product even better.

This should be more broadly adopted. Having writers on your team is good for the docs, obviously, but it’s also good for the product itself. And good products are successful products, which is really the goal for any external API.

For more on APIs, open source, community events, and developer culture at Capital One, visit DevExchange, our one-stop developer portal. https://developer.capitalone.com/