Onboard
with tooltips

Onboard with tooltips

My role

UI aesthetics issue ~ tooltips across the editor are inconsistent
UX problem ~ new users struggle with learning how to use the product

Our onboarding problem

New users are unable to learn Dark without the aid of an external source (ie: a reference or walkthrough videos).

I've been an advocate for in-editor onboarding since I joined. But we were never able to make time for the initiative until recently.

Why didn't it take be a priority?

The Navigator and the Explorer

Dark initially positioned itself as a new language; it attracted attention from the programming languages community.
These users approached new concepts with patience, willing to learn first before doing. But they rarely ship projects in Dark.

The most successful demographic, who ship projects in Dark, turns out to be new developers, students, and front-end engineers. They explore new territory and learn by doing!

How can we tailor learning Dark for the explorer?

Project tutorials. Most Javascript frameworks start with a todo list tutorial because many frontend engineers are explorers.
Tooltips have been aiding people to learn software through exploration.
They provide additional information to what non-obvious icons mean and suggest actions users can perform.
Code sharing empowers users to learn from one another and build upon eachother's knowledge.

Let's focus just tooltips for now

Let's focus one for now

Sample project tutorials. Most Javascript Frameworks start with a todo List tutorial, because many frontend engineers are explorers.
Tooltips have been aiding people to learn software through exploration. They provide additional information to what non-obvious icons mean and suggest actions users can perform.
Code sharing empowers users to learn from eachother and build upon eachother's knowledge.

Current tooltips are inconsistent

Understanding the problem

But consistency can't be achieved with just rigor to a style alone.

We got here because, every time we added a new tooltip, we aimed only to solve the current problem.

Let's take a step back to understand what we were trying to achieve in the past, and what we want to achieve in the future.

I approached this problem by...

First, found all instances where tooltips are used in the editor.

Then I categorized them by the functions they serve.

Lastly, theorized how we can use tooltips in the future to either introduce Dark to new users or highlight new features to seasoned users.

Taxonomize the chaos

Our editor has over 60 tooltips. They all fall into one of the four categories:
Labels -- provide text equivalents (in 5 words or less) to icons
Descriptions -- explain UI elements in more detail in a few sentences
Exceptions -- explain deviations from expected behaviors
Suggested actions -- tells a user to do something to help them along

Imagining a better world

Right now our tooltips have no memory. They will show regardless if the user had seen them before.

Tooltips will also need a trigger condition.

It will determine if the tooltip should appear or not. For example: has the user seen this tooltip 10 times already?

The component model

Property	Data type	Required?
Attached element	DOM element	Yes
Title	Text	Yes
Description	Text	No
Trigger condition	Function	Yes
Button label	Text	No
Button action	Function	No

Tooltip with just a title
Tooltip with title and description
Tooltip with title and action button

Decide on a style

First I made 6 different treatments.

We voted internally and chose the top 3.

Decide on a style

We voted internally and chose the top 3.

I hashed out the details for our top contenders. And made mocks for tooltips with a description and an action button.

Giving our users a voice

We asked our users to vote on the top 3 styles and this won out


then I made additional adjustments for contrast visibility

Testing out the tooltip component

When I applied the component model to exisiting tooltips, I realized we missed capturing one category.

Exceptions -- explain deviations from expected behaviors

Our component model does not capture the difference between an informational tooltip and an exception tooltip. Let's revise our tooltip model

Revised model

Property	Data type	Required?
Attached element	DOM element	Yes
Title	Text	Yes
Description	Text	No
Trigger condition	Function	Yes
Button label	Text	No
Button action	Function	No
Style	INFO or EXCEPTION	Yes

Translating the new style property into UI

INFO
EXCEPTION

Future tooltips

From watching many first time users struggle with our product, I wrote a proposal for all the places we should have tooltips to help new users learn.

For example, Dark captures all incoming data, even invalid requests. Users can use that data to construct their program. We want to make sure new users knew about this feature.

Context-aware tooltips

	Title	Handle your 404 errors
	Description	Dark keeps tracks of all incoming requests. You can create an HTTP handler populated with the data from a 404 request.
	Trigger	This tooltip will appear if the project has 404s, and the user has not yet created a handler from their 404s yet. It will appear without them hovering over the 404 icon.

Feasibility Test

If I am ever unsure about the feasibility of my designs, I will test it out first.

See the Pen Tooltips by Alice Q (@alice) on CodePen.

Implementation Kickoff

A product owner used this as a jumping-off point to create an in-editor onboarding flow. And a frontend engineer implemented the tooltip component.

Lessons Learned

Contrast check the moment I decide to apply color.
Tooltips that show by themselves should have a dismiss affordance.
I should have presented the deliverables of this project highlighting the UX enhancements first instead of styling cleanup. It would have provided greater value to our users, and I could have gotten the team onboard with implementing it sooner.