Gutenberg: Tips: Gutenberg NUX and beyond

[karmatosed]

This idea stems from looking at #2176 and how to combine with the later experience of a user. Tips is that. It has a starting point, that the user chooses to opt into - it doesn't force the experience but encourages along the way.

This is a dialogue, the design is strongly influenced by chat interfaces and AI. It would be great to use this as a chance for personality - Gutenberg supporting and guiding along the way.

Tips flow

• On first load you see a message that encourages you to discover more about the new experience.
• At any point the user can cancel, they click through every stage.
• Tips are user guided, the user at every point decides. This is important as we never take over the screen with a modal or wizard.

Types of tips

There are 2 types of tips:

• Discovery tips: the initial walkthrough of the new experience. This is a complete flow.

• Helping tips: these level up users with tips that go beyond simply discovering the interface. These tips make your experience using Gutenberg improved, they are also a way to encourage users along their journey.

The backend should be very usable also to non-technical people: all tips are created in a way that's easy for someone to add new tips of either type.

Tips behaviour

Tips has certain behaviours:

• Discovery tips can be picked up at any point of the flow, up until 2 weeks into using the new experience. After that the only tips available are helping tips.
• If a user wants they can turn off or force on all tips, either via UI or code (this allows for network enabling/disabling).

Note: we could explore the toggle setting here again, but in past we have found it doesn't work there.

• If a tip is dismissed, no tips will show for 24hours.

An alternative to closing could be:

• If a user goes all the way through the discovery tips flow, no helping tips appear for 24hours or twice opening the editor if the user didn't visit the site in 24hours. This is a starting point to be reviewed for the kind of trigger logic.
• Tips only appear once, there is no duplication of tips.
• Once you dismiss 2 tips in a row, all tips turn off and you can turn on again via the setting in ellipsis.
• Tips are spaced in how they appear. Nobody should see more than 1 tip every 2 hours of continuous use, for example. We need to discuss the exact behaviour here. It's important to not make tips a problem.

Design

Tips has an animation based on the one @folletto has used here:

https://codepen.io/folletto/pen/POaQNG?editors=1100

The idea will be it's a 'heartbeat' and this can be worked on. The UI is designed to look like a chat interface on purpose.

Props to @folletto, @mtias and @jasmussen for helping me work through this. I have my rough sketches here as a background for where this idea came from:

https://cldup.com/Lwec4SpPGp.pdf

Conclusion

I would like to see us look at tips and how initial implementation doesn't have to be huge on this. Let's discuss.

As a starting point let's also here start thinking about tips that would be useful for users.

[hedgefield]

As you know I'm a big fan of having this, so real nice to see work on it. 👍 Looks like you've thought it out quite thoroughly already, so I don't have any big points, just a few questions:

• I see in the sketches you considered an arrow instead of a dot, can you elaborate on why you chose the dot?
• The close icon/text might look better if it was vertically aligned with the first line of text in a tip.
• The drop shadow could be a bit larger for my taste, to really separate it from the content. Think Material's floating action button.
• Perhaps the drop shadow/border could be the same color as the dot? That might create a stronger connection between those two elements.
• See next might create the feeling that it _is_ a wizard, so Show me another tip might sound more casual.
• Definitely we don't want to overwhelm users with tips, but I think putting a hard limiter on them is not the best way to go, at least for the very first run. You'd want to define the 3 or 4 essential functions that we want to teach people, and _after that_ we can tone it down, just incidental tips when they open the pre-publish screen or a screen takeover for the first time maybe. With each tip they can decide if they want the next one, so that's good.

Nice job!

[karmatosed]

@hedgefield thanks for the feedback, let me dig in with some responses.

I see in the sketches you considered an arrow instead of a dot, can you elaborate on why you chose the dot?

I have considered an arrow but there are a few issues with arrows. Firstly placing can be hard and directions, secondly animation isn't as easy. We can have the heartbeat and not only be more direct, on more adaptive situations, but also have a good visual hook and call. Arrows are good for things like speech bubbles, but they aren't always the best for 'pin point' (pun intended) locations.

The close icon/text might look better if it was vertically aligned with the first line of text in a tip.

A good point, depends though if we have multiple lines and it is smaller. We can work with the closing styling though - I don't also feel it's there yet.

The drop shadow could be a bit larger for my taste, to really separate it from the content. Think Material's floating action button.

We don't use the denser shadow anywhere else on the interface. I have had it stronger in mockups but for now reverting back to the ones we are using.

See next might create the feeling that it is a wizard, so Show me another tip might sound more casual.

The trouble with words is words :) In seriousness all text is open for us. I think using terminology like 'tip' we have to be careful as that maybe isn't understood by everyone. However, we can iterate here, we also have to mindful about translations.

Definitely we don't want to overwhelm users with tips, but I think putting a hard limiter on them is not the best way to go, at least for the very first run. You'd want to define the 3 or 4 essential functions that we want to teach people, and after that we can tone it down, just incidental tips when they open the pre-publish screen or a screen takeover for the first time maybe. With each tip they can decide if they want the next one, so that's good.

Totally think we can iterate on Tip behaviour, there will be things we have to get across. I do not think that screen takeovers though are the way forward. These are bad from a user experience view, we should never just take over a screen without the user choosing to interact. That's the one key point of this experience I do not want to deviate from and feel strongly we are to avoid. An example of this is at all times the user controls the next step, they chose to go on this journey. The tips never take over the screen very much on purpose.

[jasmussen]

I dig it!

I think it would be a good idea of starting with as little as possible, get that implemented, and then expanding and polishing. All written here sounds perfect, but there's always the chance that something feels off when we start implementing it. Nice work!

[StaggerLeee]

Can tell only from my own experience, and it is of course subjective.

• When I install something new in WP and see Tips, I know I need them.
• But dismiss them directly, without reading an single word.

Cannot explain it. Like it more to explore things by myself going through all options.

[afercia]

Visual "things" that appear on the screen are often an issue for accessibility. They'd need to be announced in some way. Moving focus to a tip could be confusing for users. Announcing them with a speak message would at least inform users, but I'm unsure how to point them to the tip after it is announced.

The language used on the tooltip would probably be of fundamental importance. The tip text should avoid any visual/positional reference; instead, it should try to describe in a simple language what a control is, where it is placed and what it does.

For example, "this control on the left" wouldn't help so much, instead something like "At the top of the editor, the inserter button will allow... bla bla" would be a bit better.

[NewJenk]

These tips look really smart. Although like @StaggerLeee I often skip them, giving a brief overview of the key features seems like a great idea.

[karmatosed]

@afercia whatever we make we I am sure can tread the line and make something accessible for all. I very much agree the language here is key - this is a good point.

[folletto]

I share the same attitude of @StaggerLeee — but even in that scenario it's more I'm expecting a badly done one. Often if it's just a single tip, I'm happy about it: I read that one, get the information, and move on.

The other criteria against tips for me is annoyance: I'm _very very happy_ to see since the initial concept an underlying logic to make these not just easy to dismiss, but also delayed so they don't keep showing up all at once.

Definitely we don't want to overwhelm users with tips, but I think putting a hard limiter on them is not the best way to go, at least for the very first run.

That said, I agree this is a concern, but I favor @jasmussen's approach to start with something basic that works, and then working up with tuning, copy and subtleties.

Specifically, I think the best approach for this would be to be light on the UI and logic, and spend some time in having a clean way to write them: that would make testing and trying them out faster, and would make us learn faster. From there improving the UI, the logic, and the various criteria should be smooth sailing.

The language used on the tooltip would probably be of fundamental importance.

MASSIVE YES on this.

I personally believe that this kind of interface works better if it's a dialogue: small bits of information, on the point, and that can be followed up with other, or dismissed if I already know them.

For example, "this control on the left" wouldn't help so much, instead something like "At the top of the editor, the inserter button will allow... bla bla" would be a bit better.

This is excellent too, as it's informative in general.

—

I'd also add that this is great as a foundation "dialogue" feature, with a strong vision for the future — as it's incredibly flexible:

1. With just one tip, people can be notified of new feature in a very light way.
2. By chaining multiple tips together, they can provide extensive information.
3. In a later iteration, it can work across screens, thus doubling as a guide in more complex flows.
4. They could be triggered by help messages "Click here to be guided"!

Great work here 💖

[pento]

I'm not sure that tips are a good long term solution for introducing users to the interface - both in the block editor, and beyond.

While there are some differences, this is very reminiscent of pointers in Core, which we haven't used for years, for a few significant reasons (among others):

• An interface that requires a pointer to explain is probably more complex than it needs to be.
• Pointers are highly interruptive. They assume that the user is able to stop and deal with the message right now.
• They usually answer a "what's this?" or a "what are the things I don't know about?" question, where a more practical question is "how do I do x?".

Tips are certainly an improvement on pointers, but seem to have similar problems.

With that in mind, I find myself wondering if the different questions require different ways of showing answers.

"What's this?" is a highly contextual question, but is always associated with a specific UI area or control. I think it could be answered with a short sentence that shows on hover or long press, similar to what many modern desktop applications do, and some mobile apps.

To answer "how do I do x?" questions, I find Microsoft Office's free form help system interesting - the user types what they want to do, and it looks for keywords to match different functionality.

For the third question, "what are the things I don't know about?", I'm not sure that this question can even be answered within the application UI. It requires a lot of assumptions about the end user, and can be counter productive - a novice user won't find more advanced tips useful (and may find them confusing), whereas a more advanced user will quickly dismiss the basic tips, missing out on the more advanced tips later.

[folletto]

Thanks for your comment! I know some of the things you raise are common doubts, so it gives a chance to explain how Tips solve these and why.

Is it like pointers in Core?

Looks like that, right? This is one of the situations where a UI can look like the same, yet it's radically different. Think for example the modern form of notifications: an app can use them for useful, valuable content, with a solid background logic — they are amazing. Another app uses them to nag and annoy the user over and over with no logic — holy pineapple, the rage!

This is to say, that while Tips might look like just as a slight improvement over the pointers visually, the core of it lies in five fundamentals that are invisible:

1. The underlying trigger logic — Tips are meant to provide an API with a variety of smart logic parameters that determine when they show up (first user? first time visiting the page? did another tip just showed up? did X hours pass? etc). This is both to avoid frustration, but also more importantly to show them up only in the moment closest to the user actual interest.
2. The dialogic interaction — Tips are meant to be not merely informative on UI, but a dialogue. This means a lot of work on the copywriting to be useful, short and engaging. A lot of the value of a tip is how it's written, and that can make day and night difference.
3. The ease of writing them — Tips should be easy to author (i.e. a separate file with a clear syntax usable even by non-technical people). This allows them to be more flexible, and iterated way faster to get to a point where they are effective.
4. The guidance ability — Tips aren't just pointers, they are able to guide users through multi-step activities. This is a consequence of the dialogic foundation. Imagine clicking a help button on "how to set a post sticky" and getting a sequence of Tips that guides you through it. It's probably the most effective way to learn an interface.
5. Ease of dismissal — Tips can be dismissed at any point, either by closing them explicitly or navigating away. They also don't block any part of the UI as a modal would.

Once these fundamentals are in place, you'll notice that the issues mentioned above with the current pointers are either disappearing or reduced drastically.

Examples!

To be sharp clear, I'll show how the three questions in the comment gets answered easily with Tips:

• "What's this?" — the short sentence you mention can easily be a Tip, triggered in a way that's best contextual for the UI shown.
• "How do I do X?" — Help is useful there, I agree. And Tips would be amazing as this because instead of just writing and "telling" the user how to do things in a different screen, they will show by guiding the user through step by step. Easy, quick, and seamless.
• "What are the things I don't know about?" — This is solved by tips with a combination of the trigger smart logic and the help guide. It's however something important for some parts of the interface, and we're going to test out which parts might benefit by it.

The best thing of all of this? Tips are a single, flexible, unified system. Instead of having to design and build solutions ad-hoc for each of the problems above, we finally will have a dialogic framework for it.

I hope this helps clarifying the doubts! :)

[karmatosed]

I think it's important to note that Tips are not Pointers. As @folletto said, they are also aimed at fixing a lot of the issues pointers have. Tips also have a guiding component that is super important.

Whilst what works for you @pento in help is totally a starting place for one type of user. That's in part I think why it's hard to see this, most of us working on Gutenberg, probably do dismiss help - we're advanced users. That's in part why the combination of a guide and Tips is a solid way forward.

This solution is both aimed at those that land on the screen for the first time and go 'erm what next' and those that are using it and want to level up. It's a balance about getting things contextually when they need them. I totally agree it's a fine line and interesting to play with staying on.

Discoverability and where things are is absolutely something the UI should hint and guide with. This is an exciting thing to explore. A great example of levelling up through UI is Vimeo. They offer tips that appear as you go through your journey. Many other apps and sites have variations on this. It's worth noting, personally I found Vimeo tips super helpful and useful - interesting for Tips.

I think it could be answered with a short sentence that shows on hover or long press, similar to what many modern desktop applications do, and some mobile apps.

The issue with having points where you hover is the screen rapidly becomes cluttered. Also without intelligence they stay, can repeat and you have a lot of accessibility issues with this. What is being suggested is an intelligent system of Tips. This guides, levels up and makes sure people are not distracted.

We also with Tips can actually level up people, over simply show them what things do. The learning aspect is a very important one to remember of this proposal. As a system like this builds of course we could add in keyword matching and develop the 'AI' further. But, let's start with the process outlined and build up.

For a starting point I think we should develop the guide. It's simple, requires no AI and is what will welcome on the first load. I feel it's the scaled back option. I also am open to this being developed as a plugin if people think that's right - just to see if this works as a notion and test easier. Writing the script and a list of tips is the first step there.

[karmatosed]

We are going to strip back Tips to a first version and dive into development. Props to @noisysocks for taking on this noble task.

Firstly, this is needed and it's really obvious on first load we need something. We can however strip it back and build up the intelligence. On first load just have a walkthrough, nothing more for step one. It won't have an on/off option, if you say click the button you get the walkthrough and that's it.

From the accessibility feedback it seems 'self guided' with the button avoids some issues. Let's make sure to get a review once we have a PR though.

The design of the Tip is this:

Animation wise I'd like to bring in the codeine animation from @folletto here: https://codepen.io/folletto/pen/POaQNG?editors=1100

On first load we show how to add a block. These will only show for new users at the start, we can maybe discuss this but I think only showing the first time they make a post or page is good. I would maybe suggest we have a on/off code option for this so people can choose to not display on multisite for example, giving control feels sensible.

The story of the Tips will be as follows:

• Show where you can add a block (only showing one of the places) by a block.
• Show where/how to open the sidebar.
• Show where the preview is.
• Show where the publish button is.

I am adding a copy label so we can work on 'what' those say but for now lets get the following in as basic text (iterations will happen).

• Adding a block (this is the first Tip to show and will show as soon as the screen loads for the first time):
  "Welcome to the new editing experience for WordPress. You can add different types of content by using the '+' icon and opening the library"

• Sidebar:
  "Additional settings are available in the sidebar, just click the 'cog' icon to access it."

• Preview:
  "See a preview of your page right here"

• Publish:
  "Finished writing? That's great, let's get this published right now. Just press the publish button and you're good to go."

I note that all of that text could do with iterations, but it's good for a first pass :) We also may add more Tips, the important bit right now is getting the base in for this, then we can build up.

[afercia]

A few considerations accessibility-wise:

• the Tips should be treated like a modal: role="dialog" aria-modal="true" aria-label="Gutenberg tips (or something more meaningful)"
• see also #5242
• on first load, focus should go to the modal
• the "X" button needs a meaningful aria-label
• when clicking "See next" focus should go to the following modal
• particular care should be taken when crafting the Tips text: they should be meaningful also for people who can't see; for example: "by clicking '+'" doesn't tell anything useful to screen reader users, UI controls should be referenced by their label, e.g. "by clicking the Add block button '+'". One more example: "right here" doesn't tell so much to blind people, while "by clicking the Preview link" does
• when closing the modal, focus should go... not sure where :) Maybe to #wpbody-content would be the easier option

[karmatosed]

@afercia thanks so much for these notes, really helpful as we move into development.

[michelleweber]

A few ideas, different lengths/tones with different amounts of block-related wordplay :)

Feedback, please! We can keep refining.

Adding a block
It's a whole new way to WordPress! You're have total control over your page's structure. Click the "Add block button +" to insert different kinds of content -- text, images, quotes, video, lists, and much more.

Welcome to the wonderful world of blocks! Click the "Add block button +" to insert different kinds of content -- text, images, quotes, video, lists, and much more.

Welcome to the wonderful world of blocks! Click the "Add block button +" to insert different kinds of content -- you'll find dozens of options.

You're at the starting block! (See what we did there?) Click the "Add block button +" to insert different kinds of content -- there are dozens of options.

Sidebar
You'll find more settings for your page and blocks in the sidebar. Click the 'cog' icon to open it.

There are additional settings for your page and blocks in the sidebar. Click the 'cog' icon to access them.

Preview
Make sure your blocks fit together perfectly -- click "preview" to see your page as it will appear to visitors.

Click "preview" to load a preview of this page, so you can make sure you're happy with your blocks.

To make sure you haven't hit any stumbling blocks, click "preview" to see how this page will appear to visitors.

Publish
Finished building? Great, let's get this page published! Just press the "publish" button to share your one-of-a-kind creation with the world.

Finished writing? Press the "publish" button to share your one-of-a-kind creation with the world.

[karmatosed]

Thanks so much for this @michelleweber.

I really like the opening of:

It's a whole new way to WordPress! You're have total control over your page's structure. Click the "Add block button +" to insert different kinds of content -- text, images, quotes, video, lists, and much more.

I wonder if by saying new way to WordPress we're going to be scaring anyone? We may not. I do like the friendly nature of 'Welcome to the wonderful world' but I'm conscious to not mention blocks as not sure an end user should overly care (or have to) about them.

You'll find more settings for your page and blocks in the sidebar. Click the 'cog' icon to open it.

This I think brings it to the user and really like it. I again wonder about mentioning blocks though, same applies for preview. What do you think?

Finished building? Great, let's get this page published! Just press the "publish" button to share your one-of-a-kind creation with the world.

I am conscious on publishing someone could be publishing any type of content, positive, negative and different emotions. Only bit there is I wonder about the ! and the 'one-of-a-kind'.

[spencerfinnell]

"Add block button +" to insert different kinds of content -- text, images, quotes, video, lists, and much more.

Might be nice to mention some blocks content that wasn't as relatively easy to deal with in the Classic Editor (buttons, columns, etc).

[michelleweber]

FWIW, I liked including the block language in this text because this is a whole new paradigm for how you put a page together in WP, and I'd rather be clear from the outset. People are going to call these content bits something, and if we prompt people to think of them as "blocks," we're all speaking a common language that's useful for further explanations/support docs/etc. (Plus, they have to click on the "add block" button -- there's no way to avoid mention of blocks altogether, so we might as well take the lead with orienting people to the new language they'll be seeing.)

Might be nice to mention some blocks content that wasn't as relatively easy to deal with in the Classic Editor (buttons, columns, etc).

Yes! I'd meant to ask for suggestions of other things to mention, thanks.

[karmatosed]

🤔 @michelleweber you have a point, I'm trying to check myself on that as totally may be overly cautious there.

[folletto]

It's a whole new way to WordPress!

I'd also consider not adding anything that hints at time. I know this text can be updated later, but I imagine also the classic "Haven't upgraded" situation and users getting "New way to WordPress" months and years after it's a thing. I wonder: too much of a minor thing to worry about?

People are going to call these content bits something, and if we prompt people to think of them as "blocks," we're all speaking a common language that's useful for further explanations/support docs/etc.

Solid +1 here.
For context: I'm in large agreement to avoid jargon and WP-specific language. However, I think we can consciously add one (and likely, ONLY one) special word given the massive change here. Everyone will be speaking about blocks, so I can even suggest to maybe re-phrase that first sentence to "introduce" blocks?

Starting from @michelleweber's suggestion:

Welcome to the wonderful world of blocks! Click the "Add block button +" to insert different kinds of content -- text, images, quotes, video, lists, and much more.

Maybe something like:

Your content is organized in blocks — text, images, quotes, videos, lists, and much more. Tap the "+" icon to add new blocks.

---

Also: how can we standardize the action word? "click" is desktop only. "tap" is mobile, but I feel could be ok in desktop too (even if in a more large semantic meaning). Trying to avoid it entirely might end up with some confusing sentences. Thoughts?

[michelleweber]

I imagine also the classic "Haven't upgraded" situation and users getting "New way to WordPress" months and years after it's a thing. I wonder: too much of a minor thing to worry about?

No, I think that's a totally fair point. Since this is a new, big change, I like the idea of being a little more celebratory about that, but only if there's a decided-on point when someone goes in and updates that language. If we go more neutral, that's one less thing we have to worry about. (There's also something to be said about "a whole new blah blah blah" being potentially off-putting/scary -- "I don't want to learn a whole new thing!" -- so going more neutral avoids that as well.)

[noisysocks]

@karmatosed: Could you provide a little mockup of how these tips should look on a mobile device?

[karmatosed]

@noisysocks I worked a little on the non-desktop view. I feel let's go for an 'easy win' here. Place the indicator by 'the thing' and then have a notice below. For example:

This may need iteration as we have different placing but it's a start.