top of page
c.etz
A Usability Study
Cooper Hewitt API Site

Objective
Understand how to make an API Documentation site usable
Perform a usability analysis of the Cooper Hewitt API Documentation site in order to guide future feature prioritization.
Skills
Survey Design
Personas
Heuristic Eval.
UX Research
Product Strategy
Tools
Excel
Zoom
Adobe Illustrator
Team
Ali Cifti - UX Fellow
Duration
Three Months
Client
Cooper Hewitt
Cooper Hewitt's API Documentation Site
The goal of the API documentation site produced by Cooper Hewitt was to enable developers, researchers, and students to interact with the museum's vast collection as well as tie in with the rest of the Smithsonian.
The API documentation site needed to be usable for those unfamiliar with APIs while also allowing flexibility for those looking for more advanced features.
Overview
About
Methodology
Objectives
Computer Expert / Museum Novice

Museum Expert / Computer Novice

-
Understand how easy it is for non-familiar users to learn about museum science
-
Understand how the documentation will help users understand how the API might serve different needs
-
Understand how users see themselves using the API & how straightforward it is to start these projects
-
Understand how easy it is for non-familiar users to learn how to use the API
-
Understand how the documentation will help users understand how the API might serve their different needs
-
Understand how users see themselves using the API & how straightforward it is for them to start these projects
Issues
Research Methods
Heuristic Evaluation
Understanding Current State
Usability inspection method where evaluators examine the interface and judge its compliance with recognized usability principles
Persona Development
Understanding Users
Development of unique set of user personas intended to understand how different users might interact with the API.
Usability Testing
Understanding User Objectives
Usability research with different persona groups intended to test how these different personas use the documentation to achieve their goals. Each round of usability testing will align with one or more of the objectives outlined above.
Recommendations
Personas

Kathy Miller - Curator
I'm a curator trying to keep up with the technologies that keep being introduced to my industry.
My Wants & Needs:
Create new visitor experiences
Create search tools, design custom tours, generate VR environments
Push exhibit information seamlessly to museum website
My Knowledge:
Museum Studies
Collections
Technology

Sarah Parker - Museum Student
I'm a museum and digital culture graduate student who aspires to work as a digital analyst for a museum.
My Wants & Needs:
Learn how APIs can be used to better understand museum collections
Use the API to create data visualizations for my portfolio
Explore trends across museums
My Knowledge:
Museum Studies
Collections
Technology

Joseph Gomez - API Vendor
I'm a data scientist who has been contracted to work for the Smithsonian to develop an app that helps visitors decide which exhibits to see.
My Wants & Needs:
Train artificial intelligence models
Find trends in artwork and generate new connections between objects
My Knowledge:
Museum Studies
Collections
Technology

Nancy Williams - Computer Science Professor
I'm a computer science professor who has been looking for an API to use as a class example to teach students how to work with Python and JavaScript.
My Wants & Needs:
Find an engaging API that students want to work with
Work with an API that is well documented so students can work with it
My Knowledge:
Museum Studies
Collections
Technology
Findings
Liked, Learned, Lacked, Longed For Matrix
The Liked, Learned, Lacked, Longed For Matrix was used to condense study data and inform development which new features should be prioritized before the API site was shipped. Study topics were placed in their respective categories, and the number of participants that supported each topic is counted.
Liked | Learned | Lacked | Longed For |
---|---|---|---|
Fri., June 20 | Book It | The Academy, L.A | |
Thu., June 19 | Book It | Bamboo, Santa Barbara | |
Sat., June 28 | Book It | Cheers, Santa Cruz | |
Wed., July 6 | Book It | The Roxy, San Francisco |
Inclusion of Sandbox + 5
Project Examples +3
Glossary to Find Terms +4
Try it Out Feature +2
Error Messaging in Sandbox
Human Generated Content
Tooltips
One-Page Layout
Layout of the Homepage
More about GraphQL
Release Date
Connection with Projects
Anatomy of Record Terminology
Cross-linking Between Terms +2
Permalinking
Knowledge of APIs Scale +2
APIs Version History
Visual Explanations +2
How to Write Field Queries +2
Mapping Object Relationships
Examples in Glossary
GitHub / Stack Overflow
Glossary Filtering +2
List of Query Terms +2
Examples in Sandbox +2
Sticky Menu +2
Environment Setup
Targeted Definitions
Conclusions
From this study, the team learned how the API documentation site was serving the two user groups and found that there needed to be an additional layer of flexibility.
From this finding, we proposed the following features:
1. Jargon Translator: An overlay that would activate tooltips so novice users could gain more knowledge of API terms
2. Permalinking: Permalinking between topics so novices could understand connections between topics
3. Environment Setup Guides: A guide to teach users how they could begin working with the API on their own
Additionally, we learned that those familiar with APIs wanted additional ways to interact with the site. In order to accomadate this group, we proposed:
1. Setup of Stack Overflow Community: users wanted a way that they could play around with the API and teach others about their findings
Overall, this project taught my research partner and I that sometimes a simple visualization, like the Liked, Learned, Lacked, and Longed For matrix is the best way to communicate to development teams which features are and aren't working on a project. By having a simple table, the development group was able to more flexibly brainstorm solutions without the limitations prototypes sometimes present.
bottom of page