Two and a half years ago we built WalkHub, an open source tool that makes it easy to record Walkthrough tutorials. Recently, as part of a large refactoring, we rebuilt WalkHub in Go to make it more lightweight. We did so because we came to realise that Walkthroughs are just one type of embedded help. Walkthroughs can be great for a certain set of applications and a certain group of people, but not all users like the Walkthrough paradigm. That is why we scaled down WalkHub so that it could be integrated into other, more complete onboarding systems.
Since we launched WalkHub, one of the most common requests we got was for a way to embed additional resources into our Walkthroughs. Many customers wanted to add videos and textual documentation that explained more than the information that can practically be added through a Walkthrough. Another, related, problem is that long Walkthroughs don’t really work, especially for customers that are exploring an application. After 4, 5 steps visitors start losing attention and close Walkthroughs or blindly click through just to get rid of it.
Embedded help: more than Walkthroughs
Another problem we found with Walkthroughs is that they are not a silver bullet for all educational content. They only have a natural fit for 1 of the 3 documentation topic primitives as defined in the DITA standard:
- They are great for task-oriented help, and can show a minimal amount of text to explain a step in its context.
- They are however less useful to transfer conceptual knowledge: when you need to introduce the underlying assumptions and concepts that you are making, it is a lot easier to do so in a video.
- Reference topics that explain how an application works and can be extended will need textual content like code samples and will definitely not work as Walkthrough tutorials.
I believe that it is important to make all 3 types of instructional materials available inside an application. When you make users switch context to access documentation (e.g. by opening a new browser tab or window) there is a high probability that they will get distracted and end up forgetting what they were trying to achieve. A lot of people have multiple browser tabs open, and once you take people outside of their primary focus, they might end up checking their emails, or wake up half an hour later and notice they have been checking their Facebook wall because they wanted to read an interesting article the documentation referred them to on Facebook…
Showing help content embedded into the app could serve as a sort of breadcrumb trail to get you back to the action you were performing.
Last week we published a prototype for our EmbedHelp widget. You can see a screenshot of it below, and a live example in the right bottom corner of your screen on this blogpost.
screenshot of a closed and open EmbedHelp widget
As you can see the widget contains a number of resources: there are links to web pages (with the link icon) and links that will start a Walkthrough (the green play icon). We will also have a special icon for video resources (red icon for Youtube movies).
The help center opens web resources in an iframe on top of the web page you opened it in
Contextual help links served from your documentation system
Ideally, it should be possible to serve the content for the EmbedHelp widget from your application’s documentation portal. With a little curation it would then be possible to adjust the content in the widget to the page on which it is shown. This way you could show any type of relevant content in the context in which it is required. For logged in users you could even show or hide content on the basis of their role in the application.
This is a use case that Drupal excels at. That is why we have decided to build a back-end for the EmbedHelp widget in Drupal 8. That way we imagine our work could be used to bring the content from documentation portals that combine documentation resources with a social component (like a forum or a FAQ section) into an application.
Embedded help for everybody!
Similar to WalkHub, we are planning to make it as easy and frictionless as possible to get started with an EmbedHelp widget. For that reason we are planning to build a Drupal 8 site where registered users can fill in a form to generate a static EmbedHelp widget for their site. The basic service will be free. If this sounds interesting, we encourage you to fill in the form below. It will help us build a better EmbedHelp widget and it will enable us to send you a notification when we go live with the service.