cfpb / api Goto Github PK

We received compliments from dev reviewers on our nav. They said it's logical and makes it easy to "make something" quickly.

Can we make it better?

Proposed fixes:

• Change the order, probably moving Field Reference up
• Change the nav labels to something actionable

On April 24th, @18F hosted an API usability session where a handful of devs from the private sector reviewed existing government documentation. Our HMDA Docs were part of the sites reviewed and we got useful, real feedback.

👍 18f took the initiative to get much-needed usability sessions rolling and we can help it stay alive by following through with quick fixes and a simple backlog.

This milestone represents the first round of fixes–we committed to three things at the session. I'll be describing our usability findings in an actionable way by making an issue about them.

We received feedback from users that they didn't grasp the point of HMDA well enough. Right now the following places on the docs give context:

• The Overview section on the landing page.
• The blurb above the main nav on the landing page.
• The Putting it all together section in the Basics page that assumes knowledge of a Fed bulletin
• Basically the whole Field Reference page

We initially thought that linking to cf.gov/hmda would help but those links weren't noticed.

Proposed fixes:

• Don't give the "congressional history" of HMDA but rather explain the present state of it in the "jobs to be done" perspective.
• Swap out the federal reserve examples for what a random dev would want to know instead ("hmm....I wonder how many people get rejected in my neighborhood?")
• Rewrite the blurb on the landing page
• Something needs to happen on the Calls page because all of the field names show up there but there isn't a definition for them there
• Re-do the field table descriptions
• The overview in the Field Reference page should have come a lot earlier...
• No one is watching the video from a link so embed it?
• Don't make people go to the Learn More page on the HMDA site...there isn't anything there for devs

We received feedback that developers did not feel they had enough context around HMDA data. The places where we tried to provide that context were ineffective because:

• the language had "too much politics and not enough about the information"
• the language read like a history lesson
• links to learning more led to esoteric documents
• our link to the "What is HMDA?" video was placed in the Field Reference page, which had its own problems. No one watched it.

Most devs are also not coming to the docs from the HMDA site, so embedding the video isn't a redundant use of content.

Proposed fix:

• Let's give our HMDA video another chance. It did, after all, win a plain-language award, and we thought it was the best way to introduce people on the HMDA website too.

By the time the actual table comes around, we've subjected users to

• too many acronyms
• links to "optional" readings

The table itself lacks

• usable definitions for each field
• calls to action

NEATO: We received feedback that people were going to the Explore Page of the HMDA website to look at the definitions of fields there because they were better.

Proposed fixes:

• Bring in the definitions from the Explore page and fold them into the table...some fields won't map out right but we'll figure it out then.
• Bring in the plain language names from the Explore page too
• Maybe the field page needs to come earlier in the nav?

In API Basics:

We received feedback that the content was easy to read but annoying to take action on.

Proposed fix:

• Re-write the content using a "jobs to be done" perspective
• use bullet lists more
• give more, simpler examples

Originally we thought that if devs got to the Field Reference page, they would be interested in the "process" of making something using the API. We used this page as a place to give them the "fine print."

Intro to HMDA LAR Fine Print 101 lives at the Learn More page on cf.gov/hmda. We thought that linking them to that page would be effective.

Instead we received feedback that devs were put off by the "congressional stuff".

Still, we think they need to know how this data is reported, because the CFPB should make it clear what this mortgage data can and can't say.

We received feedback that devs were frustrated with the lack of context around HMDA data that for those who checked out the HMDA website, they found the Explore page to be more helpful than the Field Reference or Console sections of the docs.

We know that:

• Explore has the most plain language of all places that describe information in LAR
• Field Reference is not the best-looking table. It has plain language definitions, but not plain language field names
• Explore has a preview data feature with plain language

Proposed fixes:

• Get more detailed feedback from devs, having them construct queries in both places
• Add plain language names to Field Reference table. Should be consistent with Explore
• Some way to let people preview from the docs…

Right now, the UI (and maybe Qu?) doesn't allow aggregations over census tract (because it's a number maybe?). Combined with state and county, the census tract id because uniquely identifiable across the US.

Not sure if this is as simple as using a string to represent the census tract?

That was the actual feedback we got.

Proposed fixes:

• Condense/collapse content so that it serves as a reference area
• Re-work content to describe what things do instead of talking about what they are

Field names and descriptions can be found:

• HMDA Explore page tooltips
• Swagger console
• api.consumerfinance.gov/data/hmda
• Field Reference page

They should be consistent if we're to provide good context around the data. In some places there isn't even any description.

Proposed fix:

• …make names, labels, descriptions, etc. consistent.

@cndreisbach @marcesher @virtix I'll need help with this one for the first 2 examples. Will be an opportunity to explain to dev community how changes to API are handled, too. They wanted to know more about that.

Examples using Metropolitan Statistical Area (msamd)

No description

No description

Good description

Meh description

In API Calls:

• Provide a shortcut to copy the content of a response field to the clipboard. Something like this:
  

We received feedback from users that it was annyoing to transfer the responses to somewhere else.

Proposed solution:

• Figure out a way to select and copy the text in a given field. Provide the option to the user via a button (links for this use case are not on-brand).

The Learn More section of the HMDA site should be important to devs who want to build something serious.

The fact of the matter is that HMDA data has been collected and described in an esoteric way we cannot change. It is important to understand those methods in order to use the data responsibly.

For example, on its own, HMDA data cannot be used to infer causality. We wouldn't want a ton of apps that say, "Dezzie will likely get her loan application denied because she's a Mexican-American woman in her 20s trying to buy a big house on her own in the nice part of Orange County, CA."

Proposed fix:

• Remove the current links to the Learn More page at the bottom of Query Language and in Field Reference. If people find the content bothersome they will assume the same for all the other links we put in the content.
  
  
• Mention these resources in the Contribute section
  
• Mention these resources in the Field Reference (or whatever it ends up being called) page, so that devs are aware of why the names and definitions may not be intuitive.
  

Since middle of September EQUIFAX, INC. stopped having complaints with narratives. Is this an API problem?

Some of the concepts are fine, but when I tried to grab info about msamd I got the "This might take a while" message and my browser froze for a bit. It came back after about 30 seconds though.

Perhaps Swagger isn't the best solution for this API? Not a good idea to hide this console the way we hid the others. Open to suggestions/comments. Or just a heads-up.

@virtix @marcesher

We received feedback that people want to know more about the tech behind the API.

Proposed fix:

• a bulleted list of ingredients, methods, flavorings

@marcesher @cndreisbach I'm gonna need your help on this one.

On API Calls:

• If I request metadata from endpoint /data/{dataset}
• If I request metadata from endpoint /data/hmda

The page freezes (or just takes a really long time). We received feedback that this made users leave our docs page.

Quick-fix:

• Remove /data/{dataset} console
• Remove /data/hmda console

Why didn't we set up Google Analytics for this? Better late than never.

The link http://www.federalreserve.gov/pubs/bulletin found on

We may not have covered all the basics.

Suggested fixes:

• add rate limit info
• add response content type

HMDA, LAR...

slices, concepts...

...what are better ways to say this? Ways to say it once (because it's required), and do something where we never have to say them again?

I.e., https://github.com/cfpb/open-source-project-template

Can we change it with the added / ? Whether it resolves as is or not for us who are loading the page often, we don't want to ruin someone's initial experience of the site.

http://cfpb.github.io/api/hmda/

Received requests for "interesting" endpoints. I guess our slices are too boring, impractical, or don't appear useful to developers. They also assume that devs will be HMDA-aware.

Proposed fixes:

• Latest activity
• Highs and lows
• Local activity

I think we can figure these out already…? Why would we need a dedicated endpoint?

On API Calls:

• If I request anything using the "Try it out" button, the Response Body field will cram all the JSON into one line, no word wrap. I have to gingerly select this line. I can't skim the result easily. I must scroll left-to-right.

We received feedback from users that they knew they needed to select this text to use in their work, but it was hard to skim through it and select it.

Quick-fix:

• Get rid of line 177 in the CSS white-space: nowrap: https://github.com/dezzie/api/blob/gh-pages/hmda/console/css/style.css#L177
  

We got feedback from devs that there wasn't a place on the docs where we explained a change/update process. Without this they felt like building a business plan around a contribution was a shot in the dark.

Comments @marcesher @cndreisbach @virtix?