How to apply UX principles and methods to API usability?

​

Tao Dong, PhD

Sr. UX Researcher, Google

​

​

Presentation at DevXcon 2018

​

Video recording of the talk

Flutter.io

Confidential + Proprietary

My Background

Now:

• Senior UX Researcher at Google
• Current focus is on developer experience, programming tools, and API usability

In the past:

• Studied Human-Computer Interaction (HCI) at the University of Michigan and earned a PhD

Context of this talk: Flutter

• This talk will use many examples from my research on Flutter
• Flutter is Google’s mobile app SDK for crafting high-quality native experiences on iOS and Android
• Flutter’s three product pillars
• High-velocity development
• Expressive and flexible designs
• High-quality experiences

​

A Demo in Flutter Gallery

Goals for this talk

What I hope you can get out of my talk:

• You will feel inspired to apply some ideas and methods from UX to a developer product
• You will feel informed about how UX Research can help a developer product

What DX can learn from UX?

Agenda

1. What is API usability?
2. API usability principles
3. Methods for identifying API usability issues

​

1. What is API usability?

What is API usability

Column({

Key key,

MainAxisAlignment mainAxisAlignment: MainAxisAlignment.start,

MainAxisSize mainAxisSize: MainAxisSize.max,

CrossAxisAlignment crossAxisAlignment: CrossAxisAlignment.center,

TextDirection textDirection,

VerticalDirection verticalDirection: VerticalDirection.down,

TextBaseline textBaseline,

List<Widget> children: const []

})

• The usability of an API is far more than how its signature looks like or what it does.
• It’s about the total experience of using the API in a realistic context.

​

The three pillars of API usability

API Design

Documentation

Tooling

Why is API usability important?

API usability issues can lead to:

• More bugs
• Degraded developer velocity
• Frustration and confusion

Use Pleasantly

Use Efficiently

Use Correctly

2. How to make APIs more usable?

Some lessons learned from UX Research on Flutter

Lesson 1: Reduce Context Switching

​

​

Programmers move faster if they don’t have to leave their code editor to find the information they need.

Reduce Context Switching

Programmers move faster if they don’t have to leave their code editor to find the information they need.

Reduce Context Switching

Programmers move faster if they don’t have to leave their code editor to find the information they need.

Browser

IDE

Code Template

Autocomplete

Quick Documentation

API References

Tutorials, Videos, Forums

More time

& frictions

Jump to Source

Lesson 2: Help Build Mental Models

​

​

​

​

For complex APIs, help the user build a clear mental model by mapping concepts to visualizations and metaphors.

What is a mental model?

• A mental model is the user’s understanding of how the system works, which can be wrong.
• In contrast, a conceptual model represents how the system actually works.
• The user will experience usability issues if these two models do not match.

A classic example: will setting the thermostat to 90° warm up the room sooner than setting it to 80°?

Help Build Mental Models

For complex APIs, help the user build a clear mental model by mapping concepts to visualizations and metaphors.

AnimationController({double value, Duration duration, String debugLabel, double lowerBound: 0.0, double upperBound: 1.0, @required TickerProvider vsync })

​

Animation()

​

Tween({T begin, T end })

​

CurveTween({@required Curve curve })

​

CurvedAnimation({@required Animation<double> parent, @required Curve curve, Curve reverseCurve })

How do these animation building blocks fit together?

Visualize the Conceptual Model

Lesson 3: Speak Your Users’ Language

​

​

​

​

​

​

Name your API with words your target users are familiar with and can reasonably guess without look it up in the API doc.

Speak Your Users’ Language

Naming your API with words familiar to your users makes the API easier to discover.

Quiz: Can you guess what a UI widget called Block does?

Answer: Nobody knows.

Speak Your Users’ Language

Naming your API with words familiar to your users makes the API easier to discover.

What about the name ListView?

Speak Your Users’ Language

Naming your API with words familiar to your users makes the API easier to discover.

Block was the old name of ListView until early 2017

Jakob Nielson’s Usability Heuristics

2. Match between system and the real world

The system should speak the users' language, with words, phrases and concepts familiar to the user, rather than system-oriented terms. Follow real-world conventions, making information appear in a natural and logical order.

https://www.nngroup.com/articles/ten-usability-heuristics/

Lesson 4: Enable Programming by Example

​

​

​

​

​

​

​

​

Examples have become the de facto way to learn programming and API.

Enable Programming by Example

Having examples somewhere is not enough. It is critical to allow the developer to quickly locate and evaluate the relevance of an example.

“This is nice, linking to actual code. But it’s very difficult to choose which one you’d like to use unless you see the output.” -- Study Participant

Enable Programming by Example

Having examples somewhere is not enough. It is critical to allow the developer to quickly locate and evaluate the relevance of an example.

Lesson 5: Promote Recognition Rather than Recall

​

​

​

​

​

​

​

​

​

To the human brain, recognizing the right choice is cheap, while recalling it from nothing is expensive.

Examples of Recall vs. Recognition in UI

Promote Recognition Rather than Recall

To the human brain, recognizing the right choice is cheap, while recall is expensive.

Promote Recognition Rather than Recall

To the human brain, recognizing the right choice is cheap, while recall is expensive.

• The improved Colors API does not force the programmer to remember and recall the possible options.
• The preview on the sidebar also helps the program to recognize the color they want rather than asking them to remember what different shades of blue look like.

Recap: Five API Usability Lessons

​

​

​

1. Reduce Context Switching
2. Help Build Mental Models
3. Speak Your Users’ Language
4. Enable Programming by Example
5. Promote Recognition Rather than Recall

​

​

3. How to identify API usability issues?

Applying usability testing to APIs

Observing using the API in action

Photo by Charles Deluvio 🇵🇭🇨🇦 on Unsplash

Confidential + Proprietary

Confidential + Proprietary

4 steps in conducting an API usability test

​

​

1. Prepare the API you want to test

• Make a list of the API you want the test to cover.
• If the API has not been implemented, you can use API stubs in usability tests.

For example, in the “build a simple UI” study, we wanted to cover the following APIs

• StatelessWidget
• StatefulWidget
• setState()
• Column
• Row
• ListItem (ListTile)
• Block (ListView)
• Scaffold
• AppBar
• IconButton
• Colors

2. Specify a representative programming task that can be accomplished using the API

​

​

Expected results

Reference Implementation

3. Moderate and observe programmers attempting to accomplish the task

The set-up:

Study Room

Observation Room

Participant

Moderator

Livestream

Remind the participant it’s a test of the API not a test of how well they code

​

“Please remember that we are testing the developer experience of Flutter -- it’s not a test of you. So anything you find confusing is something we need to fix.”

Ask the participant to “think aloud”

“As you work on the programing exercise, please ‘think aloud.’ That means verbally describing your mental process as it develops, including the doubts and questions you have, the solution strategies you consider, and the reasons that justify your decisions.”

An example of the “think aloud” protocol

Why is “think aloud” important?

Because if we ask the participant to recount their experience at a later time, we run the risk of “forcing subjects to infer rather than remember their mental processes.” (Ericsson & Simon, 1980)

More tips for effective observation

• Know what you are looking for
• Let the participant solve the problem
• Keep track of the help you give and keep that to the minimum
• Separate your interpretation and the data

4. Evaluate results, decide if changes to API, tooling, or documentation are needed

“Now it’s the time to let the data speak!”

“But what is the data?”

Data from usability testing, ordered by reliability

• Behavioral data: what the participant did
• Verbal reports via “think aloud”
• Retrospective account
• Opinions and predictions

Summary

• API Usability is more than the shape of an API, it should cover API design, tooling, and documentation.
• There are lessons we learned to improve the usability of Flutter’s API. These lessons are likely to be useful for other APIs as well.
• Observing how developers use your API to solve realistic programming problems is one of the most effective way to identify usability issues.

Got questions or comments? Feel free to contact me at dongtao@acm.org or @taodong on Twitter.

Thank you!