Developers are humans too: Why API documentation needs HCD

For one, API documentation can be full of jargon and difficult to understand. It can also be a lengthy read, missing key information, and hard to find in the first place. Even if a developer reads documentation from start to finish, these problems mean they might not find the information they need.

Because of this, developers learning to use a new API often do a quick CTRL+F of the documentation, and if they don’t find what they need right away, they use other methods to get answers, such as:

• Searching with Google
• Posting a question in a developer forum
• Asking the API’s support team

These methods understandably take time. But if developers had accurate, complete, and helpful API documentation – something that we’ve consistently found is at the top of their wish lists – they wouldn’t need to put so much time and effort into troubleshooting.

In UX terms, the developers in our studies are asking for documentation written from a human-centered design (HCD) approach, even if they don’t use those specific terms. Basically, they want the writers of technical documentation to remember that somewhere, there’s a human reading it. Yet even though we commonly hear developers refer to this desire for HCD-focused documentation, poorly documented APIs seem to be everywhere.

How did we get here?

Some say that the programmatic equivalent of UX Writing is API Design. If this is true, then why is so much API documentation missing that same human-centered approach?

We have a few hypotheses, mostly based on who’s doing the writing in the first place.

• The engineer writes the documentation: Engineers are experts in their line of work and the intricacies of the system they built, but they can struggle to step outside of this zone of expertise to document their application in a way non-experts can understand. When you know a subject well, it can be difficult to return to basics and move from jargon to plain language.
• A technical writer writes the documentation: Technical writers are usually embedded on software development teams rather than UX teams. They often work from a set list of pre-identified audiences, such as executives, technical experts or SMEs, non-expert end users, and more. But if there are multiple audiences, it can be easy to write API documentation that is too complex for beginners or too detailed for experts.
• A UX writer writes…not the documentation: UX writers – experts in HCD – are sometimes uncomfortable working with such highly technical topics and aren’t often involved in API documentation.

Additionally, technology is often focused on the latest and greatest advancements or the newest, flashiest upgrade, according to the author of I’d Rather be Writing. If the industry is focused on new, fun functionality, then documenting the functionality itself or the story behind that functionality can sometimes be forgotten.

As a result, most documentation is written to bring the audience to the application. The technical functionality is the most important part of the documentation, leaving the person reading it to sink or swim depending on whether they meet a precise skill level and existing knowledge base.

But what if instead we shift our focus and think about bringing the application to the audience? When we recenter the human on the other end of the documentation, we also shift our ecosystem definitions. We can begin to see the schemas and parameters within the context of a larger picture, and that documentation suddenly becomes more useful to more developers. Not only that, but good documentation saves your development and support teams time by reducing the number of questions or development problems. Here at Ad Hoc, we’ve learned the value of taking an HCD approach to even our most technical documentation.

How research can help

The best documentation comes from understanding and welcoming the expertise of developers inside the team as well as developers who are likely to use the API. Elissa, one of this blog post’s authors, started her first documentation writing project by running a “documentation jam” with developers on her team: she asked them to use external API documentation (in this case, Spotify’s Web API guides) and write down how they looked for information and made decisions with it. This process helped us identify some commonalities in how one subset of developers use documentation: across the board, her teammates looked for a quick-start guide and code examples right away, and her team prioritized making those components of our documentation as well.

But simply having developers on your team doesn’t mean those developers know exactly how end-user developers will use the software. Engineering teams, and developers in general, are not monolithic, any more than the users of the services they develop are. Researchers can help bridge that gap between the domain-specific knowledge of what tech to use and how to best use it and why, by helping development teams get a better understanding of their end-user developers’ needs.

In a way, gathering this data lets end users co-write with your team because it gives them a means of piloting and reflecting on documentation at their own pace and with their own tools.

When this data is gathered and synthesized into a report, it lets your team see the bigger-picture problems, needs, and successes that apply to audiences from a variety of experience levels. When you have this information, it suddenly becomes easier to write for multiple audiences – and to write better.

With the necessary data to back up your choices and assumptions, your writers – whether they are engineers, technical writers, or even product managers – can make informed, human-centered improvements to your documentation.

Build HCD-thinking on existing technical teams

UX researchers and designers are experts in leaving their assumptions behind to find out what they don’t know. They use ethnographic research to re-learn and re-think systems, ultimately building products that work better. We can bring these same principles to technical documentation to change how it’s made and used.

This knowledge doesn’t have to be the sole domain of researchers and designers, though. We encourage engineers and technical writers to take the same step back to basics, even as they work on documentation that’s looking to the future by focusing on the latest technologies, the latest advances in coding, the most up-to-date security. At every stage of the documentation creation process, we hope colleagues in all disciplines will be invited to keep questions about their readers front of mind:

Having your team ask themselves these questions, even if they’re not UX researchers, can help them bring an HCD mindset to the documentation and development work they do every day. And when we bring HCD to the table, we welcome the humans on the other end of the application to pull up a chair as well.