Engaging Citizen Developers

Documentation for government APIs

Project Year

2013-2014

Organization 

The Consumer Financial Protection Bureau

Role

User experience and front-end development

About

There was a need for proper, modern (as in not in the form of a Word document), and repeatable documentation as part of the Bureau's work to make government datasets public.

The CFPB believes that public data should be easy to access for government transparency. It’s a major reason why we release open source software.

Design + Dev at the CFPB wanted to learn what it would take to create a call-to-action for nerds everywhere to serve their country from behind the soft glow of their computer screens. I worked with the API’s architect to develop a framework that has since been widely adapted as the gold standard for software documentation in government.

Designing the docs

I drew on my previous teaching experience to design documentation that facilitated learning, instead of just being someone's brain dump.

Learning the basics

Practicing with examples

Learning by doing

Getting into the weeds

Usability testing with Github

I reached out to developers in the Washington, D.C., tech industry and asked them to give us feedback on our first pass.They liked how they could hit the ground running with the API, but looking up details was easy to do too.

But nothing is perfect. We made a commitment to improve the docs, using Github to log all usability issues. It keeps us accountable, and allows the open source community to contribute or implement solutions.

Open-source government

Since publishing the documentation for the HMDA API in early 2014, our project has been forked by other government agencies. Whether it has transformed Word doc-based documentation into usable, findable information, or allowed our cousins at 18f to stand up their own projects more efficiently, the CFPB's docs framework has become the cult favorite for publishing software documentation.