Mark UI buttons in the guides to improve discoverability

[oleq]

📝 Provide a description of the improvement

Personally, sometimes I feel it's pretty hard to figure out which button among dozens is "the one" a particular guide is about. This could be even a bigger problem for people unfamiliar with the editor. My idea is we could add some classes via JS in the samples (and some styles) and help readers find the right place to start.

Some rough ideas

The halo approach

.ck.ck-dropdown.foo > .ck-button::after {
    content: "";
    background: #ff000014;
    border-radius: 100px;
    width: 60px;
    height: 60px;
    display: block;
    position: absolute;
    top: 50%;
    border: 3px solid #ff00008a;
    left: 50%;
    transform: translate(-50%,-50%);
    z-index: -1;
    pointer-events: none;
}

.ck.ck-dropdown.foo button.ck.ck-button {
    z-index: 0;
    position: relative;
}

The tooltip approach

.ck.ck-dropdown.foo > .ck-button::after {
    content: "Check this out!";
    background: #ff5b61;
    padding: 3px 5px;
    border-radius: 3px;
    font-size: 10px;
    color: #fff;
    display: block;
    position: absolute;
    top: 0;
    left: 50%;
    transform: translate(-50%,calc(-100% - 8px));
    z-index: -1;
    pointer-events: none;
}

.ck.ck-dropdown.foo > .ck-button::before {
    content: "";
    display: block;
    width: 0;
    height: 0;
    border-style: solid;
    border-width: 5px 5px 0 5px;
    border-color: #ff5b61 transparent transparent transparent;
    position: absolute;
    top: 0;
    left: 50%;
    transform: translate(-50%, -8px);
}

@Reinmar @AnnaTomanek

---

If you'd like to see this improvement implemented, add a 👍 reaction to this post.

[AnnaTomanek]

I soooooo love this idea, this is something that I was missing a lot, too.

Both solutions are totally fine to me. Feel free to choose one that you prefer.

[mlewand]

I had same feelings for a long, long time (don't know if it's not duplicated somewhere already), but that's definitely something worth doing.

[oleq]

The PoC code landed in https://github.com/ckeditor/ckeditor5-link/pull/new/i/6267.

Issue(s)

I wanted to enable it in different places but there's a major problem with making this tour balloon available across the project.

1. I wanted to make it a helper next to window.getViewportTopOffsetConfig() in https://github.com/ckeditor/ckeditor5/blob/master/docs/assets/snippet.js#L23-L27
2. But the tour balloon imports stuff from @ckeditor/ckeditor5-ui and the snippet.js is not processed by webpack.
3. I tried including it somewhere in snippetadater.js so weback processes the file but it's not a simple task.
4. Even if compiled along with the snippets, snippet.js imports the entire UI librabry and the famous "some modules are duplicated" appears.
5. So these are requirements for it to work properly:
   1. it must be compiled by webpack (because there are UI deps),
   2. it must be compiled along with the snippets (to avoid duplication),
   3. but only once per documentation page (where there are multiple snippets) to also avoid duplication
6. Knowing that I think there's no way to magically compile the snippet.js file and include it in every guide. At the moment of compilation, the adapter does not know which snippets will be used on which documentation page so there's no way to satisfy the last requirement (Next to which snippet the helper file should be included?)
7. I figured the only sane solution is creating a separate file for the tour helper and importing it manually import { pinTourBalloon } from '@ckeditor/ckeditor5/docs/assets/tour.js';, for instance, in build-link-source.js (followed by window.pinTourBalloon = pinTourBalloon).
8. That would make some sense except that it makes @ckeditor/ckeditor5 a dependency of all packages which guides will benefit from it, which is wrong.
9. I'm stuck.

[oleq]

cc @pomek @Reinmar

[pomek]

That would make some sense except that it makes @ckeditor/ckeditor5 a dependency of all packages which guides will benefit from it, which is wrong.

As what I could observe, we don't add docs dependencies to pkg.json. It makes sense because docs cannot be built per package. The main repository provides a script for building docs for all packages and all required dependencies are defined in the main repo.

[oleq]

So what we can do to solve the problem?

[Reinmar]

• But the tour balloon imports stuff from @ckeditor/ckeditor5-ui and the snippet.js is not processed by webpack.

I think we shouldn't do that. It's easier to code this balloon this way, but it just cannot be built like this in our documentation website. It's too complicated.

The challenge and goal here, IMO, is to code this functionality in a way which will be completely standalone and pluggable into existing editors.

[oleq]

An external library then?

[Reinmar]

Sort of. Something that can be plugged like the inspector.

[oleq]

The info balloon must be positioned absolutely and it must survive page scrolls, window resizing and target moving (the toolbar can change stickiness from top to bottom) so there are plenty of cases to take care of.

Without our internal helpers that handle this already the only sane solution I see is a library like https://github.com/shipshapecode/tether and an integration on the Umberto-side (Umberto provides an API that CKEditor guides can use to attach a balloon).

Maybe we could spend some time on it in the next iteration?

[Reinmar]

Without our internal helpers that handle this already the only sane solution I see is a library like https://github.com/shipshapecode/tether and an integration on the Umberto-side (Umberto provides an API that CKEditor guides can use to attach a balloon).

This doesn't have to be done via modifying Umberto itself. Umberto is extensible, we load some CKE5-specific scripts there anyway – e.g. the "paste from Word" notification that's automatically loaded in all snippets. This helper that we'd need here could be loaded similarly, purely on CKE5 side.

Maybe we could spend some time on it in the next iteration?

Wanna join the red squad next iteration? :) I'm going to label it so it's there.

[oleq]

Sure, I can carry it through.

[jodator]

I don't want to create another issues as the one below looks similar.

Move feature buttons before the expected fold on mobile:

[oleq]

Some lib that could help us out https://roughnotation.com/ (didn't test in, though).

[godai78]

How is that going?

[oleq]

The issue was forgotten and no PoC saw daylight. It is still a valid issue, though. Let's discuss it during the next sync and see if we can come up with some timeslot for this.

[jodator]

Move feature buttons before the expected fold on mobile:

Side idea: Marking toolbar buttons as "high" priority so they will be picked for a mobile fold.

[Reinmar]

TODO:

1. @oleq writes down requirements.
2. @pkwasnik makes a max 1 day research and PoC about possible options.
3. We spend additional ~2 days trying to turn the PoC into a prod-ready solution.

[oleq]

Some considerations

• The library to position the tooltips must have a compatible license (MIT sounds like the best option).
• The library to position the tooltips must support window scroll and resize (the tooltip should follow the toolbar button).
• We can ignore inline and balloon-* toolbars in the early implementation.
  • They would require the tooltip to show up together with the toolbar, which sounds like extra work.
  • Most of the feature snippets run on top of the ClassicEditor anyway.
• The library must re-position the tooltip as the toolbar becomes sticky to the top of the window. 
  • In other words, the positioning must be dynamic with a preferred direction (possibly north, because default buttons tooltips show up to the south).
• The library cannot pollute the DOM of the editor UI (i.e. inject nothing into toolbars or buttons) under no circumstances. It must be totally autonomous.
• The library should look good be totally not in your face. We're trying to do something subtle to help users out, this is not a CTA on a landing page.
  • OTOH the tooltip must stand out because otherwise, the whole effort will be for nothing. This is going to be tricky.

Questions

• If there are multiple editors in a single guide, should only the first editor get the tooltip? Or all of them?
  • If the latter, should tooltips hide in all editors if the user discovered the button in one of them?
  • For starters, we can use a single tooltip per guide to not answer this question yet (and avoid creating possibly complex logic to handle this).
• How to configure the feature? 
  • The buttons in toolbars have no names so in editor.ui.view.toolbar.items there's no easy way to tell if a particular button is responsible for bold or link.
  • A configuration in the snippet by simple index? attachTourTooltip( editor.ui.view.toolbar, 4, 'Click here to insert a link' ) (in editor promise)?
  • Indexing may work but is prone to bugs when someone accidentally changes the order of the toolbar button. 
  • We should be fine with the indexing approach, in the beginning, only to speed things up.
• When (whether) should the tooltip disappear?
  • When the user clicked the button the tooltip was attached to (sounds good to me but is it necessary)?
  • Should a tooltip have a mini-close button to get rid of it if it gets in the way somehow (covers some content or other UI element)?
• Should the state of tooltips survive across page visits (e.g. using local storage)?
  • Some people may get annoyed that every time they visit some demo some tooltips are bugging them even though they already recognize features and their buttons.
  • OTOH I'm not sure if samples in the guides are re-visited for the same purpose of clicking toolbar buttons. So maybe no.

[pkwasnik]

Personally I prefer it when such things are very subtle. A small indicator without a big arrow "here is the new feature!" covering the text will be enough for me. But not sure what our users will like.

TBH, after some small research, I couldn't found anything better than https://roughnotation.com/ proposed by @oleq . Most similar libraries are for "step by step" introduction. Of course, there are hundreds of tooltip libs, so we will have plenty of options if we go this way.

PoC with that library:

Main pros:

• MIT license
• no issues with scroll and resize
• it is very subtle, do not stand out too much, and do not cover anything
• animation only on the beginning, that does not distract the user while reading doc
• IMO with such a light indicator, we could show it every time without remembering in the cookies that someone already clicked it

There is one problem that will exist with every library. On the small screen when the button is behind "three dots", nothing will show up. But it could be solved by @jodator proposal: move the feature button out of the mobile fold, so it will be always visible.

Also my thoughts about some of Oleq's questions:

• IMO when there are multiple editors, only first should get tooltip, it will be annoying to see everywhere the same pointer. Alternatively "show me" button will be ok (docs are not always read from the beginning, sometimes just an interesting paragraph in the middle. So probably it could be nice to help a user find the button, but only upon request)
• Indicator should hide after a user clicks the button - the user noticed a button, so the tooltip did its job. This could be remembered in the cookies, but if the tooltip will be only in the first editor and be very subtle - then IMO it is not necessary.

So now we need an answer to the main question: do we want a tooltip, or only an indicator around the button?

[godai78]

I'd say all that is fine and I'm for. But I'd keep the indicator on all demos if we have more. These are rather rare cases, we hardly ever have more than two demos, so this is not that a big deal - especially that there sometimes are demos showcasing different toolbar options (eg. the image demo [also wanted to mention heading demo, but the second one basically requires zero indicators anyway...).

[oleq]

PoC with that library:

Can we see this live in some branch @pkwasnik?

[pkwasnik]

Can we see this live in some branch @pkwasnik?

Sure: https://github.com/ckeditor/ckeditor5/compare/i/6267?expand=1

[godai78]

OK, looks good, but there is some layer overlapping while I scroll, where the editor window would cut the mark:

Note: this seems to happen with the HTML embed widget and the image, but not with regular content and code blocks.

[godai78]

Like this:

[pkwasnik]

OK, looks good, but there is some layer overlapping while I scroll, where the editor window would cut the mark:

Fixed:

One alternative:

EDIT: another alternative:

There are several options to configure: shape, speed, stroke, iterations, color

[godai78]

Oh, the block one, much nicer than the circle one!

[pkwasnik]

Example with simple tooltip and grey indicator (updated also on branch):

EDIT:
only tooltip:

only indicator:

[godai78]

I like the idea of faint indicator very much, I'm not totally for the tooltip, tho.

[Reinmar]

My 2cs:

• The general "drawy" form looks great, IMO, because it stands out from the surrounding. It's clear that it's not part of the intefrace itself.
• As for colors – the grey proposals, especially the one with a tooltip, blend too much with the editor UI. I think that especially the tooltip could be confused with the editor's UI. To me, that a tooltip itself might actually make sense, but it'd need to be paired with a more colorful marker.
• In general, I like a green circle the most, followed by a green square. It could be paired with a tooltip if you find a value in this, but I'd perhaps start with less.

[oleq]

• IMO both indicators (pen and highlighter) only make sense when the user has a chance to see them being painted (animated).
  • If the editor is not visible on page load because it is displayed later on in the "Demo" section (and this is how most of our guides work) these will render as a static "thing" that might even look like a glitch.
  • In other words: this thing works only when you see it animating.
  • I think we could go with this approach if the animation starts when the editor shows up in the viewport (could be triggered by the IntersectionObserver).
  • For what its worth, I like the highlighter style better (2nd from Mark UI buttons in the guides to improve discoverability #6267 (comment)). I think it looks more... professional mature?
• I also like the "only tooltip" mockup.
  • It feels natural to me. Most likely because it's a battle-tested pattern.
  • I think it conveys more information than the pen/highlighter and it's easier to spot because it does not overlap with the UI of the editor (it is outside).
  • Idea: what if we displayed a circle (a blue/red one?) next to the button the tooltip is anchored to? It would immediately fall into "unread thing" category.
    • People are very much used to distinguishing unreads (badges) in UIs (messages, e-mails, notifications). We do this all the time.
    • This definitely stands out.
    • A rough sketch below.

[Reinmar]

TODO:

• Post here notes from our last meeting so we know what's the direction.
• Analyze what's here to do to have a prod-ready version of an API that the Docs squad will be able to use.
• Re-estimate.

[godai78]

Notes from the last meeting:

• Pagefold problem. When to play animations? What about huge screens, like Marek's :D.
• Animation would need to be played when the user is looking there. After it played, it looks like a glitch (especially the text-marker-styled one).
• Tooltip + something seems safer.
• The red dot is a common pattern in UIs recently. Indicates that there's something to check there.
• In case of features that have multiple buttons – just mark the first one. We need to believe in minimal intelligence of the audience.
• Tooltip must be customizable – text per demo.
• The "Show me" button will not be used – makes no sense in this option.
• When does the tooltip disappear?
  • To be decided...
• Should we use our balloon system?
  • Technically doable, but would require injecting some code into every snippet (could perhaps be automated). Otherwise, we have code duplication.
  • But why? Maybe we can just copy the code responsible for pieces of the positioning logic.
  • Cases:
    • Repositioning on page content changes, resize, etc.
    • Repositioning/hiding the tooltip when the editor's toolbar becomes sticky.

[godai78]

Basically, it seems the general consensus was that we should stick to tooltips instead, as more clearly divisible/readable.

[pkwasnik]

Finally figured out how to put it in the code, PR is ready. After working with this a bit, I have some additional thoughts about the design:

• Animations are disturbing if you see them every time when visiting the docs. They are good in a quick guide on the landing page, but not in regularly visited documentation.

• The red dot is unnecessary - why we need two indicators? one is enough. Someone could think that this is part of a UI, some kind of notification from the editor. So it could bring more bad than good.