Usability Test Fall 2015

[pyramiddig]

Thanks to the 18F group at GSA, they performed usability testing for ITA's APIs and Developer Portal. While we are still working through prioritizing the feedback, we want to extend a special shout out to Chris Barnum, Nate Nash, Ben Balter, Eric Mills, and especially Gray Brooks for their time and effort giving us great feedback.

The comments are in no special order (nor do we agree with all of it ;-) but we want to be sure we've captured all of the feedback. As we start prioritizing the recommendations, we'll create separate issues for each. The majority of the feedback focus on our Consolidated Screening List, Trade Leads, and API Key.

General Comments

• In general, let your developers be able to see at a glance what data types they will get back.
• The App Gallery is a nice touch.
• The Developer Portal has good plain language.
• Navigation is a bit confusing
  • It's not intuitive that there's only a partial API list.
  • The left and top nav are a bit confusing
• Everything should be HTTPS
• It's great that the Portal documentation is responsive design and sitting as open source in GitHub
• Consider putting Pull Request links at the bottom of each page to encourage developers to improve upon the documentation.
• Move the news from GH's wiki tool to Jeckyl, then make it available as an RSS feed.
• It would be nice to allow a limited number of requests without an API key. GitHub allows 60 requests per hour without an API key.
• The Attribution requirement is not always applicable since a developer may be using the APIs for an internal application that does not have a user interface for displaying the attribution.
• The error codes should have better documentation and link to a page that explains the problem, such as invalid API key.
• Putting a space before the API key in a query returns a 0 length response.
• Consider using “pretty” permalinks
• Update the API List page so the name of the API is the hyperlink to the documentation.
• Be consistent:
  • Use empty strings or null values but not both.
  • If we're using dates and sometimes include time then always include a value for time even if it's zero.
• Consider letting a user see the raw results after testing a query in Explorer.

Consolidated Screening List API and Documentation

• It would be helpful to have the data types up higher on the page.
  • This helps developers know what they're getting back.
• It is not immediately obvious that the sources come from different formats.
• Update Sources Used meta data:
  • This should be its own endpoint and not included in the CSL endpoint.
  • Include the source_information_url and source_list_url as part of the sources_used values.
  • Consider putting the sources_used values in their own endpoint.
• Consider making it clearer that the entity_type field is specific to Treasury entities.
• Make it clearer which fields have been normalized from the various lists
• The three tabs at the top of the documentation are a little confusing. Consider putting a box around them so it's clear that switching tabs only changes the top paragraph or two and not the whole page.
• Make the Background paragraph clearer.
• Consider splitting out the name of the source list and its abbreviation. For example:
  • Specially Designated Nationals
  • SDN
• The explanation of the fuzzy search logic is appreciated
• Encourage providers of source data to point to CSL search app or documentation.

Trade Leads API and Documentation

• Include links to any taxonomy or list out controlled value for fields that have them
  • For example, what values will the Procurement Type field be limited to?
• Consider grouping under one heading like-data from different sources that's been normalized - group the remaining data that is unique to each source under a separate heading
• Consider indexing the accompanying files that come with each procurement as they provide valuable search results.
• Consider updating the FBO data daily even though it's quite cumbersome to do so
• Include more information about the procurement opportunities such as whether they come from government or private sources and who can bid on them.
• Consider curating the data that comes from the sources:
  • Put multiple tags into an array instead of separating them by commas
  • Break out email addresses into their own fields if they've been included in the Contact field
• Kudos for using a consistent naming convention.
• Consider putting more white space between descriptions of each data source.
• More frequent updates to trade lead information would be appreciated.

API Key Process

• It's not clear where to recover your API key.
• Links that say "Get an API Key" should go to the Sign Up page not Login page.
• Consider putting the API Key in the Welcome email instead of making the user login to confirm then receive their key.
  • An alternative is to have the link automatically log the user in to receive their key.
• Consider putting the user's name in the Welcome email's greeting.

[gbinal]

👍 Rock. It's great that you all keep iterating and improving your already strong offering. Keep it up.