May 6, 2014

Write the Docs: Zach Corleissen – More Than a Reference: Better APIs through Empathy

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Zach is a technical writer at Moz where he focuses on API docs. He kicked things off with some Q&A to help guide where he’d take the talk.

For Zach, empathy is the ability to mutually experience the thoughts, emotions, and direct experience of others. It’s not exactly sympathy, though the words are often used interchangeably. It’s possible to be sympathetic without being empathetic. To write empathetic API docs, you have to understand and share your users needs. The easiest way to do this is to be an API user yourself. Dogfood your own product.

To gain empathy, gain experience. There’s no shortcut around it; you have to use your own API. Using other APIs will help you identify the strengths and weaknesses of your own API.

To write with empathy you first have to know who your readers and your API users are. To learn this at Moz they ran a customer survey; but they ended up with data that wasn’t a large enough sample size to be statistically valid. While not statistically valid it was useful. Once you’ve learned who your readers are, write for them. Write to that audience, their background, and their skills. Frequently you’re writing for other reasons than your readers. Deadlines come in to play. Business incentives force their way in.

They found their readers wanted sample code and written documentation, in that order. Ultimately code samples are written documentation as well.

The best thing you can do in your documentation is to tell true stories. If someone’s in your docs you don’t need to market to them; just establish trustworthiness. To help guide this, ask why does this API matter? True, trustworthy stories help convey that information.

Your API docs also have to provide a friendly UI. It needs to be approachable for your target readers. One approach to doing this is to use single-page docs with stronger typography.

You also must lavishly document failure states and edge cases. You can technically push this off to your support team but documenting it will save you so many headaches.

Empathetic API docs challenge you to deepen your technical skills and care for the needs of others. Deeply technical material requires you to be empathetic. Empathetic API docs delight your readers exceptionally. It turns moments they wouldn’t expect in to pleasant learning experiences.