Connected web services are the meat and potatoes of the application world today, and providers have to work hard to ensure use and adoption.

Developers are looking for APIs that are easy-to-learn and that perform as they expect them to. Well-written documentation do everything from educating users to attracting developers to start new projects with what you offer. But how do you accomplish that well-written documentation? It’s not as simple as a user manual used to be, but not as complex as designing a whole new website, either.

Technical writers and content strategists who understand the purpose and goal of excellent API documentation are few and far between (but growing!) so here are a few suggestions to ensure that the API doc you write is best-in-class.

Tell the story.

Tech doc gets a bad rap for being dry and merely focused on the functional. When you’re working to drive adoption of an API, it’s key to start with the story. Consider how adopters and users plan to interact with your software, what their goals are – also what your goals are for them, and how you want them to approach the tools.

A prime example of some pretty amazing API doc (according to developers who say so) is Twilio.

Just look at that thing of beauty. A Confluence-based setup, this doc offers the story right up front. What does it do? “Power its platform for communications.” Bingo. Then, for new users, “What is a REST API, anyway?” Super smart. This approach leaves very little to chance. And by using Confluence as the basis, that handy-dandy left nav is right there, just waiting to be accessed.

Your story doesn’t do much, though, unless you:

Offer a clear start.

Twilio gets this right again. See the first selection after “What is a REST API, anyway?” Right there.

Twilio offers a base-level explanation, followed by the opportunity to jump right in. Offering code snips, links to a trial account – it’s all right there, easy to spot for new adopters, potential clients, and even users who have been there before by offering the “Twilio Console.” It is so seamlessly integrated that it feels like you are already a client!

Design the architecture for humans.

Here’s where to avoid mechanical, dry, boring documentation. It’s reasonable to expect that lots of folks will interact with your product primarily at the documentation level. Why bore them here?

Twitter’s API doc nails this and then some.

No one who happens upon this page will feel as though they are greeted with robotic, poorly-planned text. This is written for human consumers with real application goals. “Measure Tweet performance: Build a simple tool…” Naturally, everyone will be enticed by the simplicity. And offering a tutorial? Perfect. This is where developers can come to learn what they need and avoid fluff and jargon.

Don’t be anything less than all-inclusive.

It’s flummoxing to arrive at what you hope to be comprehensive documentation only to find that it isn’t! Document everything, document it thoroughly, and document it well. Look, if someone doesn’t need it, they won’t read the extra, but if it’s missing? That’s just deadly.

Look at how smoothly GitHub handles this:

Again, a Confluence-based (or inspired, at least) instance, GitHub organizes everything but the kitchen sink in the list of guides in the navigation panel. All of a user’s questions are answered, or referenced, in that panel. Quick start guides? Check. Building / installation? Check. Each of those navigation titles heads to a page with more information, labeled and cross-tabbed. It’s dream doc.

Highlight learning opportunities.

Never miss a chance to teach. Never. The more your users know and understand, the better you are and the fewer help requests you’ll field. Back to Twilio for an excellent sample:

Products: API docs, quickstarts, and tutorials. All right there in the left nav, with a nicely-organized set of tools to learn. Sweet. It would be virtually impossible for someone to NOT find what they need to learn here. Chances are good that by offering both Quick Start guides and tutorials, all that a developer needs to ramp up is right there for the taking.

And finally, perhaps the most important of all:

Update everything, all the time.

Keeping doc up-to-date is a challenge, I know. Resources are stretched thin, writers work on multiple platforms and products. It’s the same old story. But here’s the thing: if your doc is out of date, then the perception is that your product is as well. The literal only way to ensure adoption and use is to stay on top of the docs. Even if you are sure that users are only reading 1/3 of them, it’s still imperative to head back in and troubleshoot, revise, and update consistently.

If you want people to adopt, you must update.

(I think I’ll use that as my next motto!)

Happy API Writing, fellow tech writers. Do it well, and you’ll rarely be thanked. But do it poorly, and you will suffer great pain.

I wish you well on your API journey. It’s sure to take you far.