TAO DONG: My name is Tao Dong.
I'm a UX researcher on the Flutter team.
So today, I will talk about API usability and some lessons
I have learned from doing API usability studies on Flutter
and through observing how people actually use the API that we're
providing the SDK.
So why is API usability important?
It's because API usability issues
can lead to bugs in your code, and some of those bugs
can be mission-critical.
And it also makes programming less efficient and less
enjoyable for other people.
But when we talk about API usability,
it's actually not just one thing.
And we need to care about three complementary areas.
And they're API design, tools that
make APIs discoverable and usable,
as well as documentation, which explains
how to use APIs and libraries.
And often, you can find that one API usability
issue can be solved in many different ways
within this space.
So how can we make APIs more usable?
Here, I share some lessons we have learned from UX research
on Flutter.
The first lesson is reducing context
switching during programming.
And here, I specifically mean programmers
can move much faster if they don't have to leave their code
editor to look for the information they
need for a problem they encounter during programming.
That's why it's pretty common to see programmers
where they look for information in the source code of thr ID,
instead of going to their web browser
and look for online references.
So having a lot of documentation is obviously a great thing
to have.
But what matters more is how and where the user of the API
is going to access most relevant information during programming.
I'm a strong believer in high-quality API documentation
in the source code itself, because that way,
you don't require the user of your API
to switch a context to somewhere else and risk not getting back
to the original task.
The second lesson is that, as API designers,
we should help users build a clear mental model when they're
dealing with complex APIs.
So in a recent UX study we ran, we
observed that participants had trouble understanding
how different building blocks in Flutter animations
were related to one other.
And you can see that you have to really digest these concepts.
So one potential way to address this issue
is to visualize the conceptual model of such a complex API
using a visual representation, like this one,
and then map different APIs to draw in the parts of this model
and also leverage some familiar mental models
that the user may already have.
The third lesson is speaking your users' language.
Anyone knows what the Block widget does in Flutter?
It's OK if you don't have a clue, because nobody really
knows.
[LAUGHTER]
But if I ask you about this widget instead,
who knows what ListView does?
I bet many of you do.
But you probably didn't know that Block was the old name
of ListView until early 2017.
So very early on, we found that users really could not
find Block when they were trying to find a widget that
can scroll a list of things.
And then we changed the name and made the widget much easier
to discover.
And the next lesson is enable programming by example.
Everyone loves examples, but that
does not mean having a bunch of examples somewhere
is good enough.
We used to have a feature that we thought was clever.
We had a link on our website, which will allow the user
to search for all the usage of an API inside of the Flutter
repository.
But the result?
That it only overwhelmed our users,
because there were so many, and none of those
had screenshots to tell you which one is the one
you are looking for.
As this study participant pointed out,
it's kind of overwhelming.
So what did we realize?
That having a curated and focused simple code in the API
documentation itself and in the same time
provide screenshots, illustrations, to show
the output of that piece of code is really important
to guide the user and to help them quickly understand what
an API does and decide whether this sample code is
relevant to their task or not.
The last lesson I'd like to share today
is that the API and tooling should really
promote recognition, rather than recall.
As an example, probably a lot of you have used this Colors API.
But this API used to require the user
to remember specific values for different shades of the color,
and it also used a map to store these colors,
store these values.
So you kind of need to remember the specific number
to use this API.
And it also does not autocomplete well,
because the map keys don't autocomplete.
After realizing there was a problem with this API,
we redesigned this API and made sure all the shades
of a particular color would show up in the autocomplete box
and also added a little preview on the sidebar of the Code
Editor to tell you which exact shade that you have selected.
So these changes have turned a pretty expensive recall
operation in the user's head to a less expensive recognition
operation in the user's head.
And this is also a case where API redesign can really
enable tooling.
So these are the five lessons I wanted to share with you today.
And you, as our community, can really
help us make a difference by reporting issues in usability
from your own experience, and give us your ideas,
and potentially submit PRs to fix some of the issues.
And there is an unconference session tomorrow on this topic,
if you are interested in further discussions.
Please come.
I think it's at 2:30.
And thank you very much.
Looking forward to further discussions.
[APPLAUSE]