Is your documentation AI and chatbot ready?

It seems likely Artificial Intelligence (AI) and chatbots will play a key role in helping users, in the future. Amazon, Facebook, Google, IBM and Microsoft, as well as smaller technology companies, are all developing platforms for simulating an intelligent conversation with human users.

This raises a question:

Will chatbots mean we’ll write a how-to task in the chatbot app, again in the Help, and again in the tutorials?

It’s not very productive to write the same content three times, in three different places. It makes even less sense if you need to update the content on a regular basis, or translate that repeated content into multiple languages.

One solution is to store different types of data in its native format until it is needed, and then serve that information to the AI or chatbot system. You write the content once, and “serve” it to the chatbot, the online Help, the tutorial, and so on.

This requires that content to map accurately to the chatbot’s information structure  –  the use cases; the user’s intent, role and sentiment; and the entity (i.e. the problem and product) that relates to the user’s question.

As a technical communicator, this means you can start by making sure your content is in a structured format. For example, it has metadata (and uses a taxonomy) that will help the AI system or chatbot know which piece of information to serve the user. This includes common metadata such as product, symptom, problem, version, user role and operating system. It may also include new metadata relating to responses based on the user’s current mood (“sentiment”),  and the context in which the question is made to the chatbot.

This approach makes it more likely that your documentation will AI and chatbot ready, at the time when it’s needed.


Tryo Labs has published a useful summary of the different approaches and technologies you can use for creating chatbots. See: Building a Chatbot: analysis & limitations of modern platforms.

See also:

Towards content lakes

Cherryleaf’s technical writing services

The ROI of user documentation: you could break even if you avoided 3 support calls per week 

We’ve been experimenting with another spreadsheet for calculating the Return on Investment (ROI) on User Assistance.

We wanted to look at: how many support calls an organisation needs to have resolved by users reading the Help content instead of calling Support, before it starts to see a return on the cost of creating the Help.

Using typical costs for an average sized software application, the figures suggest you could break even if you avoided 3 support calls per week.

Chart showing the ROI of user documentation

Contact us if you’d like a copy of the spreadsheet, so you can make your own calculations.

You also find a related Support call cost reduction spreadsheet on the main Cherryleaf website.

The new marketing funnel for software and other technology products

Prospective customers today know more about products than they have ever done. Many people tend to search for the solution to their problem on the Web and through Social Media before they buy a product or service, and many of them never even touch the product before buying it. This means the “marketing funnel” has changed into a loop. At different points in that customer journey loop, User Assistance can help people move from being prospects to be customers and advocates:

The new customer journey loop

Getting users to read the Help rather than call support

We spotted an interesting statement by the “Father of Behaviour Design”, BJ Fogg:

“For somebody to do something – whether it’s buying a car, checking an email, or doing 20 press-ups – three things must happen at once.

The person must want to do it, they must be able to, and they must be prompted to do it.

A trigger – the prompt for the action – is effective only when the person is highly motivated, or the task is very easy. If the task is hard, people end up frustrated; if they’re not motivated, they get annoyed.”

See Ian Leslie’s article “The scientists who make apps addictive“.

If we want users to read Help text instead of calling the support line, then we maybe we need to meet those three criteria.

We can assume the user is motivated to fix their problem.

We can write instructions that are clear enough to make them able to solve the problem.

Where some applications fall down is they don’t prompt the user to read the online Help. The link to the Help text is often tucked away in the right hand corner of the screen.

Instead, we could put some of the Help text into the User Interface or the dialog screens,  and we could prompt the user to follow a link to more information. Doing this could get users to read the online Help rather than call support.

The return of Clippy?

Are we seeing the the spiritual child of Clippy emerge? Truth Labs’s Stelios Constantinides has written an article on his experiments with conversational UIs.

Conversational user interfaces (CUIs) are a spoken or written way of interacting with a device. CUIs aren’t completely new, but they’re becoming smarter, more natural, and — therefore — more useful.

Here’s where CUIs come in: since users already spend so much time in apps like Slack, Facebook Messenger, and even plain-old email, why not integrate your app inside these platforms?

Microsoft ClippyConstantinides  looks at the design process of creating something that doesn’t come across as a robot, and isn’t as annoying as Microsoft Clippy.

This links in with Ann Rockley’s concept of Intelligent Content: “Content that’s structurally rich and semantically categorized and therefore automatically discoverable, reusable, reconfigurable, and adaptable.”

For conversational user interfaces to work well, they need to be automatically discoverable, adaptable and semantically categorized. Microsoft Clippy wasn’t, which is one of the reasons why it failed in its purpose.

It’s still unclear whether this will lead to content being seen as code, or stored in a semantically rich format and inside a content management system. Whichever way, it’s important to recognize that the conversational language is different from written language. We speak differently from the way we write, and this is reflected in how we use messaging apps and authoring tools. Conversations are typically a one-to-one form of communication.

With Siri, Google Voice and Cortana closed off to most developers, we’re likely to see conversational user interfaces developed as alternatives to these applications.

One school of thought is users will move away from searching using sentences, and, instead,  learn to type commands (they will write command line instructions). In other words, they will begin to think and type more like programmers. This is illustrated in the image below.

Slack command line

I wonder if this might be a bit optimistic. There are many people find Twitter too difficult to use, and I suspect it would take them a long time to adapt to this approach.


This topic is something we cover (albeit briefly) in our Advanced technical writing & new trends in technical communication training course (the next one of which is on the 22nd of March).

See also:

(With thanks to Simon Bostock)

What do you think? Share your thoughts using the comment box below.

How technical documentation helps the customer journey

Here is a diagram that shows the different types of User Assistance that can help users as they progress through the customer journey:

how user assistance helps the customer journey

Supporting the user through the customer journey has become more important, partly because the subscription, “try before you buy”, sales model means users can stop being a paying customer at a moment’s notice. Today, all of the information you provide, both pre- and post- sales, needs to provide the same consistent, high quality, experience to the user.

Have we missed anything out? Let us know if you think the image should be changed in any way.

A technical communication user’s hierarchy of needs

At the TCUK 2015 conference, Rachel Johnston mentioned the idea of a content maturity model. We thought we’d take this idea and ask:

Could we develop a model that illustrates a hierarchy of needs for users of technical communication (and in particular, User Assistance)?

A model of what?

We suggest calling this model a technical communication user’s hierarchy of needs. This is because we’re considering the different points where a user interacts with technical communication content, the information they need, and value it gives to them.

It takes a similar approach to the content maturity model Rachel suggested (shown in the photo below), with the least mature organisations providing just the legal minimum, and most mature content systems contributing to branding and evangelism.

content maturity model diagram

A user’s hierarchy of needs also enables us to compare this model to similar models from content marketing and product design. For example, the categories in our model’s hierarchy roughly correspond to Peter Morville’s “User Experience honeycomb”, as well as the key elements in product design.

Continue reading “A technical communication user’s hierarchy of needs”

Common sense isn’t always common

Here’s some examples from Munich of what might seem to obvious and common sense to the one audience, but not to others.

Traffic lights that have four lights, with the symbols , O, I and K:

Munich traffic lights

Pedestrian crossing lights that have two people instead of one:

Munich traffic lights

The second set of lights is still comprehendible (hold the hand of the person next to you, whilst you’re waiting to cross the road 😉 ), but the first set didn’t make sense to even the (non-Bavarian) German members of our party.