Unobtrusive help system to onboard new users

[olizilla]

unobtrusive | ʌnəbˈtruːsɪv |
adjective
not conspicuous or attracting attention: the service was unobtrusive and efficient.

Is being inconspicuous an important goal?

Perhaps not directly. I think the main point was that help should be easily available for those that want it and shouldn't distract those who dont want it.

Other valuable goals would be

• Maintainble, and always in sync with the current UI
• Localizable, via transifex and https://github.com/ipfs/i18n
• Legible and accessible
• Linked to proto.school work and IPFS documentation endevours
• Crowdsource / Allow folks to add their own annotations (discussify?)

What does an unobtrusive help system look like?

Your thoughts here!

[olizilla]

Maybe https://introjs.com/ ?

[lidel]

I'm for it, given the educational mission of UIs maintained by IPFS project, we should aim to provide contextual help using the same visual language across all UIs.

I like the idea of something like introjs/hint for one-time onboarding coupled with persistent icon next to various values in UI that may need explaining. Both should be using the same visual indicator, perhaps something like:

If we want it to be unobtrusive, the first step would be to come up with convention for linking to relevant docs from UIs. Right now we can link to docs but it will look like any other link. To make it legible and accessible cursor: help will not be enough, we need a consistent hint on top of that, eg. mentioned indicator icon:

Some Vague Technical Term

[olizilla]

A few folks have expressed a dislike of introjs style "guided" intros as a help system.

@ericronne suggested a similar idea to you @lidel in that we have a visual indication where the user can get more info about a term, and clicking on it brings a glossary into view, scrolled to the term in question, but also allowing the user to scroll around to read about other terms that we have more info on.

[ericronne]

It might be good to offer a combination of one or two approaches.

I think some folks find guided tours useful, provided the associated panels or whatever are easily dismissed, and never return unless the user seeks them out. Figma's onboarding experience has a few things going for it, which could be instructive.

Figma onboarding

Initial web-app launch

Modal panel with brief welcome message appears. Opportunity to see tips or click the X to exit. Ideally the close X would be more prominent, and clicking it would forever close the walkthrough (it returns, unbidden).

Individual feature explanations

Click Next to advance to a feature description, with a nice animation for each.

Learn More links

Each panel has a text link which opens the help site in a new tab.

Return to onboarding at any time

After dismissing a panel, the user can re-enter the walkthrough via a sticky (boo) question-mark button in the corner of the page.

Regardless of what tack we pursue, i hope to contribute to the design as much as possible 😇 thx!

[fsdiogo]

I like the idea of something like introjs/hint for one-time onboarding coupled with persistent icon next to various values in UI that may need explaining. Both should be using the same visual indicator, perhaps something like:

I can see the benefits of having something like that, but honestly I'm not a big fan of this solution. We have many technical terms, I'm afraid the UI would become cluttered and the user would have to play a bit of Where's Wally.

I much prefer a guided tour, I really love the Figma example that @ericronne pointed out. That's really the best of both worlds, as it teaches the user how to use the app and clearly shows the app capabilities. As a bonus, while showing all that we can have links and/or explanations of the technical terms.

@ericronne suggested a similar idea to you @lidel in that we have a visual indication where the user can get more info about a term, and clicking on it brings a glossary into view, scrolled to the term in question, but also allowing the user to scroll around to read about other terms that we have more info on.

On GitHub, if you press SHIFT + ? a modal with the keyboard shortcuts appears, we could have something similar like that with some terms:

---

We should focus on what we really want out of this help system:

• (A) Show what you can do with the Web UI and teach how to use it
• (B) Learn about the more technical concepts about IPFS and its capabilities
• (C) A mix of those above
• (D) Other

Having this well defined on our heads will help us choose the best solution.

I think (A) should be the priority for now, it will eventually bring a bit of (B) too.

[fsdiogo]

intro.js style react libs:

• react-joyride
• react-user-tour

This is another style that could work in a simpler page:

[ericronne]

That's ☝️gorgeous. Also TIL a new github trick, thanks @fsdiogo!

A shortcut such as github's shift-? could be very handy, provided we let the user know that it's there.

[lidel]

cc #756 (Display help when pressing ?)

[olizilla]

@fsdiogo is working on a demo of react-joyride in webui

[fsdiogo]

Also, taking @lidel's suggestion, we can have a way to trigger helpers in specific places to show info about specific things instead of having to take the tour:

[olizilla]

@fsdiogo can open a WIP PR for that, so we get a preview build link that we can all try out? Other things that'd be rad

• A chardin.js demo for webui
• A shared doc to define the sections of the web ui, what they do, and what needs explaining. This might work best as a google doc to get us started.

@ericronne are you up for leading the charge on how this should be presented to the user?

[fsdiogo]

Just opened a WIP PR with a guided tour in the Status and Files page.

[fsdiogo]

I've created a google doc so we can share insight about what should be present in each guided tour.

cc @ipfs-shipyard/gui @terichadbourne