Our latest podcast – a round up of recent news in technical communications.
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.
Here is an interview we carried out with Mark Baker, author of Every Page is Page One. The interview is interspersed with audio snippets from Day 1 of the UAEurope 2017 conference.
- Caroline Loverage (Thermo Fisher Scientific). Teaching by Example: Worked Examples in the Documentation of Complex Systems
- Kelly O’Brien (Kayako). Practical Information Architecture: Building Templates For Better Content.
- Helena Pichler (Nominet). AsciiDoc to Responsive Webhelp: Agile documentation for small teams/
With thanks to Matthew Ellison and Mark Baker.
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:
From the Cherryleaf Podcast: We ask, should marketing and technical communiations be unified?
From the Cherryleaf Podcast: We look at getting users to answer their own Support questions – why would we want to do this, and how can we do this.
In researching what developers wanted to learn about writing documentation for users, the most common issue related to how much, or how little, they should write. One developer said:
“I would want to know what is the minimum I should write. If you can persuade me what is the necessity of each thing I’m capturing, and the voice I should use to make it most acceptable, I think I’d tune in.”
We’ll look at this question in the Writing Skills for Developers course, which we will be releasing soon. In general, you need to:
- Meet the legal requirements (which differ depending on the product, and the country).
- Provide enough information so that users don’t give up using your product, if they get stuck. For example, how to install the software, and how to get started.
- Consider the support calls, and whether you could avoid any of those by having good user documentation.
That might appear a bit too vague, so let me go back to one of the sentences above:
“If you can persuade me what is the necessity of each thing I’m capturing”
Before you start writing, you should define the purpose and audience for each deliverable you create. There should be a use case:
- Without documentation, is it clear what the user should be doing? is it clear what the user should be doing first?
- Is it clear how they should be doing the task?
- When they have to choose between options, do they have enough information to make the right decision?
- When they have completed a task, do they know what to do next?
- Are there any concepts or terms the user might not understand?
You can assess what topics to cover by doing some basic usability analysis. However, if you think about the tasks, the process (workflow), and any unfamiliar concepts, you will be on the right track.