The world’s greatest APIs have many similarities and differences, but there’s one thing that virtually all of them have in common: great documentation. API integration can be a nightmare without solid documentation, forcing many developers to give up. However you slice it, you can’t overstate the importance of API documentation.

At our 2024 Austin API Summit, Laura Rubin, Staff Technical Writer at Nylas, joined us to talk about improving the documentation experience for readers and writers alike. According to Rubin, there is often a disconnect between consumer expectations and the reality of hastily thrown-together docs. Below, we’ll cover the salient points and some actionable insights from Rubin’s talk.

Identifying a Need for Better Documentation

There are many different criteria to consider when assessing the quality of an API’s documentation. In her talk, Rubin points out some scenarios that typically indicate the documentation needs a little work:

• There are long implementation times or high rates of abandonment.
• You have a high volume of support tickets or GitHub issues on open-source projects.
• It takes a long time to close sales (such as for an API-as-a-product)
• The net promoter score (NPS), a metric used to measure customer experience, is low.

Ironically, she says, rapid growth often results in some of these issues. Generally speaking, growth is a good thing for smaller companies. It can, however, result in a high-pressure environment that requires quick turnaround times with little room for organization. Unfortunately, this trajectory can result in FUD — fear, uncertainty, and doubt.

“This is what happens when you have a decentralized group of people writing docs. You don’t know who wrote it, when they wrote it, why they wrote it, if it’s done, or whether someone has edited it,” says Rubin. This leads to people spending more time fighting the toolchain or figuring out where they need writing, as opposed to actually developing helpful content.

Of course, knowing your docs need some polishing is only half the battle. The next step is figuring out where and how you should be trying to improve them.

Finding the Right Areas for Improvement

Developers get very close to the products they work on, lacking the fresh eyes of a newbie, making it difficult to answer the question: “Can someone new figure out how to use your product just by reading the docs?” Rubin suggests enlisting the help of new hires for this, provided they haven’t been tasked with using your APIs during the application process.

No new hires around? Another source of truth is your support team. “They know where all the bodies are buried,” Rubin jokes. They can provide you with bug reports, common UX issues people find frustrating, where they typically send users to get more clarity, and so on.

But, as Rubin also observes, “documentation is not a substitute for good development practices.” Sometimes, docs folks can write around frustrating UX issues, but not always. “If you’re working closely with an engineer,” she suggests, “it’s a great time to say, ‘instead of calling this ID, could we call it calendar ID so it’s more clear?'”

You can also consider adding opportunities for users to provide feedback within your documentation: email links at the bottom of each page, “Did you find this helpful?” with thumbs up or down, and so on. “But,” Rubin adds, “as a counterpoint, they’re going to lie to you. They’re going to be mad, but they’re going to feel bad about typing abuse into a box.”

An alternative is to look at their behavior through analytics dashboards, search logs, and other things that let you actually see what they’re doing. You could also look at the bounce rate or how many pages are referred from different sources. “That sort of stuff does not lie,” says Rubin.

All-Purpose Documentation Tips

As an experienced technical writer, Rubin offers up a ton of advice for folks trying to write documentation. One tip is to craft helpful developer materials. “Code samples, examples, use cases. That stuff is wonderful [even if it’s not exactly what they’re planning to create] – don’t make people guess what the end result might look like.”

But she also encourages zooming out and adopting a more holistic approach to API docs. “You can have a perfectly described endpoint, but if you don’t know how it goes together with the rest of them, it just looks like a jumbled mess when what the users really want is instructions.”

“Be organized,” she continues. “Even if it’s just putting things in alphabetical order. Readers will always assume that there’s some purpose to the order, and they’ll try to guess what it is… until they’ve tried everything they can think of and assume you’re just being chaotic.”

As such, writers should consider a multi-faceted approach to improving documentation. In addition to thinking about readers, Rubin points out that we need to consider the maintainers: “Once you have good docs,” she states, “usability for the people maintaining them is how you keep docs good.”

What, in practice, does that look like?

• Own the docs, co-own it, or split it up and own it. “If it’s everybody’s job, it’s nobody’s job.”
• Write things down. Spell out the ‘how’ and ‘what’ for future maintainers.
• Progress over perfection. Don’t be afraid of an iterative process.
• Opinionated tooling. Plugins, linters, and automation tools will reduce decision fatigue in the future.
• Consistency. Build a mental model that users can follow across all your products or services.

On that last point, she echoes the Similar Hallways model championed by Kristin Womack in her talk at our 2023 Platform Summit). “Even if you don’t think they are,” Rubin cautions, “readers are always [looking for patterns and] building mental models of your docs.”

Think Like a Writer (Because You Are One!)

As Rubin points out, good writing is essential to good documentation. And, while we might not think of API documentation as being on par with the Great American Novel, “good writing” in this scenario shares a lot of the same characteristics we can expect from the sparse prose of novelists like Ernest Hemingway or John Steinbeck:

• Omit needless words.
• Avoid past tense and passive voice.
• Use simple words and avoid slang. Rubin suggests using Global English, a literal and logical form of writing.
• Progressive disclosure. In other words, do not infodump.
• Don’t use complex terminology where it isn’t necessary.
• Demonstrate confidence, says Rubin. “Don’t say, ‘This should return a 200.’ Be confident! It does.”

As APIs evolve through versioning and deprecation, so should their documentation: good documentation is a journey, not a destination. The earlier you start treating docs as cyclicly written, consumed, and edited, the more painless that iterative process becomes.

One last thought on this comparison: thinking like a great writer means thinking less about yourself and more about your audience. What are they expecting? Are there conventions they’re used to? Are they ‘getting’ the story you’re telling? All while applying existing best practices.

Well, nobody ever said that creating great documentation was easy!