This is part 4 of our Software Support and Artificial Intelligence series. You can find an overview of the series on our introduction post. If you are reading this before all posts have been published make sure to sign up for our AI & Docs mailing list, where we send notifications when we publish these posts and similar content.

What to do when you are the tailor that makes “The Emperor's New Clothes”?



I have a confession to make: I have come to believe that most Walkthrough projects are doomed to fail. The past 4 years we’ve been working on a Walkthrough solution, so this is kind of a big deal...

Ever since we launched WalkHub , our open source Walkthrough solution, I’ve been monitoring my reactions whenever I encountered a Walkthrough on a web application. Great was my apprehension when I realised that in most cases, I would simply dismiss them.

Often I wasn’t patient enough to click through the onboarding Walkthroughs that I triggered in applications. I dismissed them, or simply raced through them, barely noticing and definitely not retaining the lessons that I was supposed to learn from them. When the same Walkthrough was activated more than once, I got annoyed and tried to quickly escape. I can imagine that some users that clean their cookies regularly might find this an exasperating experience. This is why we haven’t implemented the autostart feature in the WalkHub project yet, even though plenty of our customers requested it.

In fact, I now believe that this is what most of our customers think they want from a Walkthrough solution: a means to disrupt their visitors with information and I believe it is a self-defeating anti-pattern. It is all kinds of wrong when we expect our customers to be more patient than we are.

Embedded help is there to help the user, not to sell your product

Often application owners look to Walkthrough tutorials to help drive adoption of underused features. But this is extremely dangerous and easily becomes too pushy. With interruptive documentation patterns, we need to be especially careful to monitor for annoyance. A model that triggers the display of help content that is not personalized can do more harm than good.

In hindsight, I think the problem is that we don't expect Walkthroughs to be adjusted to our specific needs. Walkthroughs are currently used as a tool to sell the features of a platform, not to help us find the feature we are looking for.
The models are not smart enough. Walkthroughs shouldn’t be used as a "world atlas" that forces customers to remember all the features of a product, they should be used as a “GPS" that shows customers only those features they need, exactly when they need them.

To maximize utility, we will need to react intelligently

I think we need a solution that is more like the co-worker in the office, who watches over your shoulder, or bumps into you with just the right advice at just the right time. But with proactive models we will need to watch out for a few things:

  • Watch for signs of annoyance: Well meant useful advice might trigger an emotional rejection in a moment of stress.
  • Don't overdo it: Just like the co-worker, too much intervention might become creepy, especially when it seems the customer is under surveillance.
  • Build trust: At all times the system should serve the customer, customers shouldn’t feel they are being manipulated.
  • Build confidence: The system will need to be accurate. Wrong help suggestions, especially when they are delivered at an inconvenient moment, will make the customer expect that none of the system’s messages are relevant.
  • Customer in the driving seat: The customer should never feel they have lost control of their browsing experience.
  • Minimize cognitive load: It will be really important to provide minimalistic content that is as economical as possible and that delivers only the necessary information. Interruptions will need to be limited to a minimum, and shouldn’t be too intrusive.

It is unlikely that static algorithms will be able to fulfil all the above requirements. We need more than a single static model of our users to be able to give them an experience that will feel human. What we are looking for is a system that can intelligently react to information about a user’s behaviour. What we need is a system that behaves almost like a human.

Walkthoughs are dead, long live Walkthroughs

I think there is a place for Walkthroughs and for embedded documentation that interrupts the user. But I think we need to differentiate between use cases and not try to solve 3 problems with the same tool:

  1. Onboarding Walkthroughs
    Rich, multi-media Walkthroughs can be great to catch the attention of first time users. I believe that Walkthroughs are valuable to onboard new customers and to explain new features in context. We have decided, at least for now, that we don’t want to pursue this market, there are a lot of tools already available to craft rich custom-tailored experiences.

  2. Comprehensive documentation
    Documentarians at software product company are asked to create an exhaustive list of howto tutorials for their product’s manuals. This needs to be fast and easy, this shouldn’t be a creative design process. We have been reworking WalkHub to make this as fast and easy as possible. We are about to relaunch WalkHub as a browser plugin that lets you record Walkthroughs on any website, annotate them and then create a GIF from the process. When the application changes you need only to re-record the screenshots and re-use the annotations from the existing GIF.

  3. Embedded help
    When you want to increase engagement, and give your customers access to documentation right inside your application, it makes sense to embed your documentation. Ideally you should be able to embed any kind of help content. We built embedthedocs.com to make it easy to embed videos, text, or Walkthrough GIFs through a help widget. Our Drupal module can be installed into an existing Drupal help site where you manage the widget's content. We are looking for a few more partners that want to run a pilot for personalising embedded help. But more about that in our next post.



Other posts in this series:
Part 1: Documentation at a crossroads
Part 2: The Helpful co-worker model
Part 3: Clippy: misunderstood brilliance before its time
Part 5: Automated proactive support as embedded messages



Interested in AI for Documentation? Sign up below and we’ll email you updates on our research.

Subscribe and get notifications about the next parts in these blog post series!

About the author

Kristof van Tomme

CEO, Co-founder

Kristof Van Tomme is an open source strategist and architect. He is the CEO and co-founder of Pronovix. He’s got a degree in bioengineering and is a regular speaker at conferences in the API, DevRel, and technical writing communities.