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?”