Don’t Let Bad UX Kill Your Open Data – Part 2

by Stuart Ridgway, Original Music for Film and Television.

You can see my presentation on this topic at the UXDC 2015 conference.

This is Part Two in a series that identifies opportunities for improving the experience when working with open data. In Part One we established that there are at least two primary opportunities. In this article we look at the first: improve the UX around documentation for APIs. I am building an app called Kittinder! An App for Setting Up Play Dates for Your Cat and want to show you where the UX for open data documentation needs help.

To do this we’re going to walk through the customer journey I take while working with data sets from three organizations: PetCensus, The ASPCE (American Society for Promoting Cat Emotions), and Tinder. As we look at the documentation, note the different facets of UX that could use some help, especially:

Interactive Design
Information Architecture
Visual Design
Usability
Communication

The first thing to remember is that developers and software engineers are people too. Just because they read and write code all day doesn’t mean they don’t appreciate and respond positively to a friendly visual design. Too often API documentation is thrown into a table and the developers are left to fend for themselves.

Imagine being welcomed by the visual treat to the right as you try to understand how to access the PetCensus data. Fortunately, I come from hardy folk so I will power through, but most developers would look at this and find another source for the information — certainly not the response PetCensus is looking for from visitors.

Because API documentation is presented on web pages, standard UX practices apply:

Responsive

You never know where a developer will be when s/he decides to check out your data. Make the documentation site responsive so when I’m at the bar dreaming about creating Kittinder I can look at it on my phone.

508 Compliant

You know you should. But don’t look at it as a chore to do after the fact. If you build in 508 compliance from the start then you naturally integrate alternate channels of communication.

Plain Language

Developers often speak many languages but the organization’s self-important jargon is not one of them. Stick with plain language and make sure the message gets across.

Developers Have Specific Use Cases

Information architecture is paramount. Most likely the organization has to give a lot of different instructions, so organize the documentation for the various APIs logically. Consider this example navigation from the ASPCE where the documentation is organized by Search APIs, Rate Limits, GET APIs, and POST APIs:

Search API
Search API: Emotions by Place
API Rate Limits
API Rate Limits: Chart
GET statuses/emotions_timeline
GET statuses/user_timeline
GET statuses/home_timeline
GET statuses/show/:id
POST statuses/destroy/:id
POST statuses/update
POST statuses/emotions/:id
POST statuses/update_with_media

Furthermore, the documentation pages for each API should be organized similarly to each other. For every API, the ASPCE provides the following:

Background: Explain what the API does and any unique qualities it has.

What the Data Is: Clarify what information is included in the data set and why it might be important.

Ideas for Using the Data: Help developers out — just because they found the API doesn’t mean they know what to do with it.

Resource URL: Provide a clickable link so the developer can see the API in action. Put the resource URL in a code-like font such as Courier to give a visual cue that this is usable code.

Search Parameters: List the different queries (data calls) that a developer can make to access different subsets of the data. Again, include clickable examples so s/he can immediately see how the data is filtered by the different queries.

Return Values: Provide clear, plain language descriptions of all the data fields that are returned with a query.

Taxonomies: If any search parameter or return value is limited by a controlled vocabulary or taxonomy, then provide additional documentation around that vocabulary. Additional points for providing an API to that taxonomy!

Remember: you want to help a developer know what to expect when they start toying with the APIs.

More Common Sense

Organizations that provide APIs have few touch points for interacting with developers and software engineers. Make sure they capitalize on those opportunities. For example, if you’re using a collaborative space like GitHub to house the documentation, include a Pull Request button at the bottom of each page. This enables developers to submit suggestions for improving the documentation. Open data begets collaboration.

Include a Change Log page that welcomes developers and lists all of the changes that the APIs have undergone. Invite them to connect with the organization on the Contact Us page. That should include the org’s Twitter handle (for announcing API updates), StackExchange address, email address, RSS feed instructions, feedback channel(s), and GitHub address. The more ways a developer can interact with the organization the better. Finally, include some News. If a developers can read about successes with the data, the more likely they’ll use it, our ultimate goal.

In part three of this series we’ll explore the API endpoints themselves and call out where there’s opportunity for improving my user experience when working with the actual data.

Stuart Ridgway also composes original music for film and television. You can find out more about his music and the Emmy Award winning television shows he works on at Pyramid Digital Productions, Inc.