Making API documentation work

Making API Docs Work
API Usability and getting people to contribute to open source @CFPB

How this project came about.
T&I wanted to use the release of HMDA data as an opportunity
to engage the developer community. Understanding that HMDA
data could get complicated, Clinton Dreisbach wrote
documentation for the API. Desiree Garcia and Mehgan Iulo
were asked to make it look presentable.

The result
intuitive
nav
context
quick
start
github
github

Concepts provide examples
Introducing something new
and unique to HMDA API and
reinforcing it with a real
example.
Making the basics relevant
right away

Can be harder or simpler
Making the entire thing
available to play with
Always allow going back
Always allow making it harder

Level of detail and focus
Skimming over the details
helps with the big picture and
prevents cognitive overload
Without losing those who
really need it

2
Win!
So we forget about it!

3
It sounded so much cooler than it was
▪ 6 people from private industry invited to do a usability study on 3
government API documentation sites
▪ Companies:
▪ GovTribe
▪ API Academy
▪ iStrategyLabs
▪ Sites: HMDA Docs was one of them, SAM API, USAjobs
▪ Note that SAM API kinda took our work and changed the colors on them
▪ Study was a think aloud free-association thing for 5 minutes plus ?s
▪ CFPB docs were perceived as an ideal

5
▪ “It’s so easy to use”
▪ “wonderfully laid out and
organized”
▪ “lots of just in time moments”
▪ “great to see embedded calls”
▪ “[that HMDA site uses the
API] that’s awesome”
The bad
▪ “It looks like a show-off science
project”
▪ “sounds like terms and
conditions”
▪ “can’t find any definitions”
▪ “congress stuff”
▪ business plans, stagnant
Overall Findings
The good
Cool but I would’t use it.

3
Following up with a thank you note
Committed in front of the industry visitors that we would make changes
to improve their experience.
1. Fixing what was freezing
2. Adding more examples (
3. Trimming the fat on gov-speak (approachable)
The highest hope being that they would check back and contribute this
time.
The worst case being that we would do nothing and they’d lose trust;
another instance of “more talking no doing”

Why usability and user experience is an afterthought
3
My take:
▪ The dev community represents the ultimate power user.
▪ Usability is perceived as a non-issue because we know all the
workarounds
▪ There might even be some triumph to figuring out something that is
disorganized, tricky, and unintuitive.
This isn’t the real problem.

2
The problem is not one of ability and skill.
It’s one of motivation.

3
Open source success and motivation
▪ People have a perception of what government-produced software is
like, it’s not attractive, and it puts us at a disadvantage.
▪ If we invite the dev community to contribute, we have to work extra
hard
▪ We have to pitch it in such a way that gives the promise of, “this will
be different”
▪ But it can’t stop there–once they arrive at our documentation or other
content, it needs to continue being different
▪ This was the strategy for the first version of the docs. It made them
successful but also posed the biggest challenge:

2
Responding to usability
findings using Github

3
Why use Github?
1. use of a place where devs already are means we’re catering to them not us
2. shows that our repos are not stagnant after successful launch
3. if one of us can’t implement changes, there are ways for others to do it

3
Using Github to file usability issues
User feedback —> Open Github Issue
Describe the problem using UX or
usability tone
Show screenshots if applicable
Propose a solution with screenshots
Make the fixes needed actionable steps

3
Interaction improvements: crashy

3
Interaction improvements: fields

3
Interaction improvements: nav

3
Content improvements: basics

3
Content improvements: relevance

3
Content improvements: faster context

3
Content improvements: jargon

“How do I know this stuff will be there in 5 years?”
The deal breaker for those who want to create serious work–the
unknown cannot be accounted for in a business plan. Less
talking and more doing–no activity on a project after launch is
seen as abandoned.
How do we communicate our change process outside the
Bureau?

Engage in a way that would make Picard proud
“API developers who want to build tools using the API can
browse the documentation”
“Software developers should check out our API and documentation.”
“…we encourage you to contribute to the project on GitHub”
“Here are the docs on that.”

Devs are users too.
Not speaking to developers in the user research portion of the
HMDA project is a homemade example of assuming that we know
our user. API Documentation, likewise, is not for expert HMDA
users.

Mortgage data is boring.
This is like promoting a MOOC on Latin grammar.

I ate my own dog food.
In order to empathize with developers, I had to see if I could learn and
do using my own documentation.

Making API documentation work

More Related Content

Viewers also liked (17)

Similar to Making API documentation work (20)

Recently uploaded (20)

Making API documentation work