Something I’ve noticed lately while looking over the API docs for a few well-known web services is that a lot of them lead with something that comes across as tacit admission of low-level hostility toward users and potential users.

Twitter’s docs do it by making the rules of the road the very first section of the docs:

Foursquare’s new version 2 API docs do it by leading with rate limits:

And even Flickr—a pretty classy establishment when it comes to interacting with their community—does it by outright admonition:

The best integrations contribute to the Flickr community by encouraging members to converse, share, and curate. Integrations that primarily use Flickr as a photo storage service or a stock imagery provider miss the point behind photo sharing (as well as violate the Community Guidelines). In other words, participate!

(from the Overview page at the Flickr Developer Guide)

All of these examples are indications early in the documentation that the API provider anticipates bad behavior on the part of the user, whether that’s doing something that violates a copyright or trademark, abusing the server, or just not doing something that’s in the spirit of the service. I don’t object to anticipating bad behavior; it happens and has to be handled. I don’t object to making each member of the documentation audience aware of terms of service, acceptable use policies, and technical limitations; nobody gets a license to crap on your hard work. What I find objectionable is the frequent implication made to every reader that they’re the next likely abuser. It’s not the most common case, it’s discouraging, and it doesn’t engage readers.

The fact is most readers will never abuse the service in question. That’s because most of the readers will skim that one page and never give those docs another look (bounce rates being what they are). Moreover, the users that do build something with the API aren’t going to abuse the platform, simply because most applications, like all applications, will be small, have limited visibility, and built in good faith. If you provide an API, take a look at your API usage: is most of your traffic attempted abusive or fraudulent activity? More likely, most of your API traffic is ordinary activity that doesn’t warrant your organization’s attention (if that’s not the case, docs may be the lesser of your concerns at the moment).

Moreover, this style of informing readers of the rules and regulations isn’t engaging. Rather than exciting users by telling them what they can do (or better yet, providing an example they can do themselves), starting with such language tells readers that the most important thing is what they cannot do. These kinds of docs discourage readers by creating an adversarial relationship, rather than exciting readers and bringing them around to a particular way of doing things.

Instead, I think it’s best to treat audience members like the adults they (probably) are. That means making expectations clear without passing judgment. In the case of Flickr’s “miss the point” admonition, it’s easy to pivot from admonition to encouragement, while still making the same point:

The best integrations contribute to the Flickr community by encouraging members to converse, share, and curate. Flickr’s more than a photo storage service or a stock imagery provider; Flickr is a photo sharing community (with Guidelines). Participate!

It’s not a big change, but it goes a long ways toward addressing the common case: earnest users with an earnest desire to know more about a system. It doesn’t coddle by ignoring the fact that the are limitations, but it also doesn’t accuse. Like so many of life’s problems, you can avoid these sorts of documentation missteps by taking a step back and asking, “Is this how would I like to be treated?”

A lot of documentation contains step-by-step directions like this:

1. Click the Add button.
2. In the Name field, enter your first (given) name.
3. Click the Save button.

This is a pretty poor, though common, practice. I’ve committed this offense against readers myself, because it’s so easy to do. Or, rather, it’s so easy to not do the important bit. Here’s what I should have done:

1. Click the Add button. The What’s your name? dialog appears.
2. In the Name field, enter your first (given) name.
3. Click the Save button. The user list appears with your name added to the list.

The difference in the second case is that the steps not only tell the user what she should do, but it also gives her clues about what to expect from each action.

Setting expectations is hugely important, particularly with software. If you’ve ever done usability testing—or even some tech support for mom and dad—you’ve seen what happens when people don’t know what to expect. Someone successfully works through a series of steps, only to stop, unsure whether they’ve done the right thing even when they’ve worked through the steps flawlessly.

This happens when the person working through the steps doesn’t have a way to gauge her own success or failure. This problem is often minimized when working through directions for physical objects, since many of our real-world physical interactions have dramatic feedback. For example, if you wanted to tell someone how to start a car, turning the ignition typically has clear feedback, with simultaneous vibrations, sounds, and visual indicators to demonstrate success and failure.

While most user interfaces provide a minimum level of feedback on interactions (e.g., a button cycles through an animation when clicked), software, with its heavy abstraction from the physical world, frequently cannot provide a more visceral sense of success or failure. With the added complexity of numerous mouse clicks and button presses to complete even simple tasks, it’s no surprise that users get confused even when they’re doing everything right.

And that’s why it’s important to set expectations in your directions. It’s not enough to simply tell your audience what to do, you also have to show them what success looks like.

Occasionally, someone asks me what I do, meaning, of course, what I do for money. Unless I’m feeling especially coy, I say that I’m a technical writer. I’m not sure I could come up with two other words that produce blank stares more reliably. People have no idea what I do.

Through their friends, neighbors, television and movies, I think people have a understanding of a wide variety of professions. Teachers, factory line workers, middle managers, police officers, computer programmers, soldiers, doctors, musicians, and lawyers have all made appearances in film, television, and our lives to the point that most people have at least an idea (however wrongly conceived) of what those people do to pay the bills. As a technical writer, I don’t have the benefit of media* (favorable or otherwise) to help people understand what I do. Superficially, people might think that since writer is in technical writer, what I do might be a bit like what Stephen King does. With the exception of a common tool of English prose, it isn’t.

To break the uncomfortable silence, I usually follow “I’m a technical writer” with “I write directions for software” or “I write computer manuals.” Although this bears some resemblance to the truth, directions and manuals seem to conjure up some uncomfortable associations, namely: Mr. Frustrated IKEA Assembler. And while I’m sure the illustrator behind the IKEA guy can be considered a technical communicator of a sort, it’s not the association I want to make because a) it has very little whatsoever with what I do and b) people hate that guy. If I were to be honest, I would say that I:

• write user guides for nerds people setting up websites,
• write internal documentation for my coworkers,
• record how-to videos,
• write HTML and CSS to pretty up all that stuff,
• program tools to make my work searchable and to analyze how it’s being used, and
• analyze data and review my work to find areas for improvements.

Aside from a light protest of the “No, no, I write directions for computers” sort, I don’t go into that kind of detail. Primarily because most people don’t show an interest, but also because I’m not going to be able to give people a general sense of what a technical writer is by explaining my work.

What I do is divergent from many of my fellow technical writers (not just from apparently everyone else on the planet). In my cohort of English-major technical-writer-types from school, there are few who write documentation for software, fewer still who work with web-related software, and fewer still** who write documentation about web software for technical, non-layperson audiences.

I try to acknowledge the fact that there is a huge variety of work in the field of technical communication. To describe it in the most general terms, technical communication is about standing between technical, domain specific information and making it accessible to people outside of that domain. Frequently, that domain is something technological, such that I openly resent resent Steve Jobs for absconding with one of the best ways in which it’s possible to think of technical communication: it’s being “at the intersection of liberal arts and technology.”

Unfortunately, I can only provide a somewhat limited (and geeky) perspective on what technical writing and technical communication is all about. So I find myself stuck telling people I write software manuals. It’s an affront to my profession in a sense: technical writers add a lot of value in a lot of different and frequently unexpected ways, but I’m not making a case for it.

In an effort to make up for this affront to my profession, forthcoming posts to this blog will attempt to explore some of the nuances of my work. In the coming weeks, I’ve got a lot of posts planned that may give you a greater insight into what it is this particular technical writer does.

* The only exception I know of here is the main character in Zen and the Art of Motorcycle Maintenance. However fascinating and well written the book is, it’s not exactly a useful portrayal for the purposes of describing my job.

** Just one, actually: this guy.