Even though it has become much easier to create embedded help experiences, many software products still do very little to integrate their help content into their application. In this post we will explain why embedded help leads to better experiences, why we built our Help Widget, and give you an overview of its architecture.

Why you should embed your help content

Printed documentation manuals are a thing of the past, or are they?
Very few projects take full advantage of the new capabilities that a connected world is offering. Most documentation efforts for web applications follow the paradigms developed in a time when documentation was a stand-alone printed deliverable, prepared as a reference source that customers would use to solve their problems.

If your documentation is not readily accessible from your application this is a missed opportunity: your customers are getting a worse experience and your support team is paying the price. Bombarded by an ever increasing torrent of information and impulses, people's average attention span is getting shorter. Users are impatient, expecting just enough information right when and where they need it.

Embedded help anticipates a user’s need for help and supports through examples or a walkthroughs in situ - or just the relevant morsels from the documentation - with the least disruption to workflow and focus. It is only a breadcrumb trail that leads back to the original action.

Actual manuals only come into play once the same users want to learn a complex new skill or process, gain a deeper understanding and confidence by having a reference.

Relevant help content embedded in the interface saves time, improves user experience and reduces support calls.

There are a few paradigms of embedding help content into a web application, you can read our overview about them in this previous blogpost. Take into account that your app will be changing, because it well should and will change: inline help needs rewriting, walkthroughs may break.

The embed help widget we created is your quick and simple solution to your UX problems without/while redesigning your app. A widget that opens on top of your application or website: you can pop up text, walkthroughs, videos etc. You can link in the relevant parts of your evolving documentation, explain complexities without crowding the app's UI. The widget's content is rendered by our Drupal CMS, so while it looks part of your interface the help content can be edited independently on the fly.

Embed any kind of online help resource into your webpage or web application. Serve contextual links from your documentation system.

Why we built the WalkHub Help Widget

We announced this January that Walkhub had been rewritten: it now uses Go and React.js. We also introduced our brand new WalkHub help widget and our intention to set up a Drupal 8 site where registered users will be able to create their own widgets. This site, embedthedocs.com is the result.

We created the EmbedTheDocs freemium community service for the purpose of allowing everyone (even those who are not familiar with web development) to create their custom instances of Help Widget for embedding documentation, including but not at all limited to walkthroughs. With this tool you can generate a widget in no time as it does the dirty work for you.

create: register/log in, create help widget, add content via form, save and test; embed: copy js embedcode, embed in your app, your widget is live; iterate: edit widget's content anytime

You can read more information about the Walkhub Help Widget in our previous blogpost and on EmbedTheDocs.com itself.

If you're curious about how widgets are generated technically with the assistance of EmbedTheDocs or if you'd like to do some fine-tuning, the next section will be interesting for you.

How it works

Drupal 8 provides the content and the Walkhub server processes it

widget created: drupal saves widget form, drupal transforms content into json, every json outpur receives unique url, url is accessible to anyone; code embedded: js code connect with walkhub server, walkhub server receives json output via its url, walkhub server builds widget content from json output; content iterated: widget's content mirrors any changes made in the form

We have separated the widget generation into two fundamental pillars: the user specific content elements (groups, links and WalkHub walkthroughs) and the engine, which generates the widget itself.

After registering and logging into the site, you can freely start adding a custom Help Widget, which is technically a node created of our widget content type in the Drupal 8 system. This content type has a simple multiple value paragraph field, which allows people to add their group-, link- or walkthrough elements as they wish:

How to create a widget

After saving the content, it is processed in the background by our custom module which uses Drupal 8’s impressive controller and routing system to generate a special JSON output of the paragraph field values. Finally the rendered JSON file can be reached through the embedthedocs.com/json/{nid} url. Our module also creates a block with the embed code, which already contains the generated JSON file’s path, so it’s ready for use. After saving the widget content you can instantly see how your widget is going to look like on the bottom right corner of the content’s page.

The WalkHub Help Widget

Once you are finished creating your own widget node on our Drupal site, you only need to copy and paste the generated embed code in your website’s source code. The code also contains the WalkHub Record button by default, so you can create walkthroughs easily on the target site. If you don’t want the Record button to be generated into the code, simply uncheck its box when editing your widget node. You can of course generate as many widgets as you need. In a Drupal system the easiest way to embed the widget’s code is to create a custom block and paste the code into the block’s body (it only works with text formatters that allow div and script tags). Once you are successfully done with this part, you can see the orange “Get help” button in the bottom-right corner of your site. You can also relocate the button easily by altering the data-position attribute of the div tag (bottom-right, bottom-left, top-right and top-left positions are available).

Your help widget is actually generated by the Walkhub engine. The server receives the JSON formatted file from the embedded code in the data-list-url attribute, and creates an HTML iframe object with the assistance of the client.js and embed.js JavaScript files (the generated embedcode already contains them) . Then it extracts the information from the data-list-url attribute for building the content for the widget using React.js components. The browser uses CORS headers for verification.

It should also be noted that thanks to Drupal’s flexible content editing feature, an existing widget's content can be edited anytime on the fly. The widget adapts to content-changes immediately on every site where its code has been embedded: the JSON formatted source file mirrors the widget-node’s content.

How to serve widgets from your own Drupal 8 site

You don’t necessarily need EmbedTheDocs to create Help Widgets, you could also generate them from your own Drupal 8 site on your own server.

This is where things get really exciting! With your own site you could serve documentation content that is targeted for a specific user, or make a widget that automatically recommends relevant content depending either on the page that a user is visiting or on their role. You could add a support chat, or a search function that looks for relevant documentation, ...

The Help Widget is generated using the WalkHub engine which is part of the project that we open sourced previously. We haven’t created a feature with the configurations to make a Help Widget module but this shouldn’t be too much work. If there is sufficient interest we will make a package that explains how it is done.

If you are interested in creating your own server for aggregating and serving your documentation, let us know here!





About the author

Kitti Radovics

Senior Front-End Developer

Kitti started to work at Pronovix in June 2015 as an iTrainee, and this was the first time she met with web programming. During the trainee programme, she evolved a lot on the field of theming and Drupal site building with the assistance of her colleagues. Now she is a Front-End Developer and Site Builder at Pronovix and she also takes part in Devportal architecturing.