An API is a method of communication. At best it’s a tool to make building software easy, but at worse a time-waster and constant hassle. Good APIs abstract complexity and quickly provide clear valuable data, whereas bad APIs abstract too much, don’t allow for any customization, or aren’t clear and therefore are difficult to use.

API documentation then is another layer of abstracting information for a developer user to decipher. By pairing documentation with an API you’re providing your user a codex and path to success. Documentation for a good API will provide meaning, structure, clarity, and the right expectations to help developers succeed.

All this furthers the API, a largely intangible process, into something we can contextualize. Then visualize. We use documentation and the interaction of the API to paint an architecture in our minds that helps the developer consumer understand the relationships between objects, classes, and functions.

Documentation is the most important piece of content an API provider can produce. Today, we’ll collate the most fundamental best practices for API documentation, but also offer new perspectives on developer portal customization, user empathy, and UI tricks to improve the overall developer experience.

Documentation: Key for End-To-End Developer Experience

Most architects know that good documentation is a mixture of demos, getting started guides, and tutorials. Having a sandbox is wonderful as are copy/paste snippets for a variety of languages. What will take this experience to the next level is developing key persona user journeys. Let’s unpack that a little:

Think of a novice developer discovering your API for the first time. Maybe they arrive with a little programming experience, but certainly aren’t familiar with the hurdles of setting up a web API connection. What info do they need? What will give them enough context to learn but also to see early success and find enthusiasm for the product?

In contrast, consider a seasoned developer. They dream Node.JS and eat APIs for breakfast. They are interested in quickly digesting parameters, understanding unique functionality, or learning advanced suggestions on how to maximize the API offerings. These deep edge cases would overwhelm the new developer, but create excitement for someone who wants to expand their horizons.

Not to mention, think about a developer who is consuming your API in an enterprise setting. They have deadlines and often have one single problem they want to solve. They’re past prototyping and need to push something out the door that doesn’t break. What would their experience look like?

By developing user personas and rooting your process in a foundation of empathy your team will be able to double check work throughout the process. It could be as simple as: “Would our beginner persona find X valuable? If yes, add. If no, consider editing or removing”.

At the end of the day, teams
At the end of the day any way that teams can remember that their work seeks to improve an actual human’s life and work really makes even something like technical writing seem far more important and impactful.

Personas are a great way to get started with that practice.

Assume Zero

When describing their technology in site copy, service providers often use verbose language that is distancing for some. For example, when you talk about “frameworks,” what exactly do you mean? The term may have different connotations to developers on another team, or even among colleagues. Eliminating assumptions in service descriptions will force your team to clarify terminologies, and therefore relate concepts more clearly to users.

Being explicit in your language and conscious of jargon is a great way to remove bias in the way people will understand your API. One way to achieve this is creating a glossary. As semantics change, and word meanings vary depending on context, a glossary can align your team and improve your public voice.

Documentation Metrics

One tool for documentation is the use of heatmaps and very simple user metrics. There are numerous tools out there that offer heatmap capabilities, such as CrazyEgg or Optimizely.

Using heatmaps could grant unprecedented insight into problem areas and underused page elements. These analytics can expose when a page is too long (nobody scrolls that far), when something doesn’t work (gee a lot of people tend to hang out on this one paragraph), and even what types of users you’re attracting (huh there’s a lot of people that scroll right to the Ruby SDK).

By combining a heatmap with something as simple as the Page Analytics extension, you can get a much clearer picture of where problems might be.

Prioritize Aesthetics

Success is certainly dependent upon the content and functionality of an API, but great visual design is critical to the navigation and discovery process. Here are a few key best practices to follow:

• Show don’t tell: Even the most eloquent and clearly described documentation will pale in comparison next to something that shows immediate value.
• Use quality aesthetics: Users may be staring at your documentation for hours, so consider how to make it more visually pleasant. Allow for generous margins, calm yet contrasting colors to promote accessibility, and a typeface that emphasizes readability.
• Information hierarchy: Consider how to partition your information into easily consumable bits. Consolidate descriptions into sections, and use subheadings and diagrams to aid readability.

Testing Documentation Experience

Often API design or documentation teams get really close to their product. They literally dream about it (maybe you too?). Attention to detail is great, but it’s also necessary to consider an outsider’s perspective. Therefore, if possible, apply primary feedback and user research methods; outside opinions can then be used to improve the documentation experience.

We’ve previously written on what questions to ask when accumulating user feedback. You can gain valuable insights by watching a new user, hearing their thought process, and allowing them to elaborate on certain actions.

Even small comments made during a research session can completely change the way the team thinks about their work. Similarly, if there are any questions about a new iteration, A/B testing can offer metrics to help decision-making. Luckily enough, Google Analytics along with Optimizely and CrazyEgg listed above offer A/B testing capabilities.

Final Thoughts

Devoting time to visualize the entire documentation experience can help elevate a boring technical document into a piece of art. As an API’s main point of contact, documentation has high value and must be treated as your most important form of content. Investing more time on API documentation can align your team by gaining consensus on language, expose areas of weakness or complexity, and most importantly: delight your users.