Assistant Building

In working with many flows for many customers, Mavenoid has identified a number of best practices for writing flow content. Here is a collection of the lessons we've learned.

Overall philosophy

The primary focus is to write instructions that are accurate, useful, and easy for the end user to understand and follow. Here are some rules of thumb to help achieve that.

Write with the end user in mind

When interacting with support tools, users may be stressed or struggling with something necessary to their work or daily life, they may be in locations or situations that are noisy or badly lit, and they may not be using their first language. Be empathetic and generous.

Correct your grammar and spelling regularly

Flawless instructions are much more trustworthy than those with many errors. Even small errors affect credibility. Try to write correctly even at early stages, rather than looping back to correct errors later – it's easy to forget them.

Use simple language

The product you're writing about may be complex, but the language you use shouldn't be. Infrequently used words slow down readers and make your text hard to understand. Common words are understood by more users and can overcome language barriers. Using simple words will make the product feel simpler to use.

Examples:

• Instead of "Attempt", say "Try"

• Instead of "Inspect", say "Check"

• Instead of "Initiate", say "Start"

• Instead of "Require", say "Need"

• Instead of "Proceed", say "Continue"

• Instead of "Utilize", say "Use"

Use natural language

Write in full sentences and don't be afraid to add extra words if they make sentences easier to understand. Try reading your sentences out loud - do they sound awkward or stilted? Rephrase them to how you would actually talk, such as if you were explaining something to a friend over the phone.

Aim for being on point without being robotic. Be neutral without being minimalist. Have a tone that is friendly rather than overly-polite or formal. Be on the user's side rather than pitying.

Make it useful

Just because you've explained something thoroughly, it doesn't mean that your information is useful.

Just because you've explained something accurately, it doesn't mean that you've explained it in a suitable way.

Even if your sentences are grammatically correct, it doesn't mean that readers understand what you want to say.

How to talk to the user

Call the user "you"

Address the user as "you" as if you are speaking directly to a single person.

Example:

• "Can you hear any unusual sounds?"

Avoid referring to the assistant as a person

Avoid writing "I" or "we" to refer to the product assistant. It should be clear to the user when they're being guided by the automated assistant and when they're chatting to a real person.

Example:

• Instead of "What can I help you with?", say "What do you need help with?"

• Instead of "We believe the problem can be fixed by resetting the unit", say "The problem can be fixed by resetting the unit"

It is okay to use "we" to refer to your company, such as when explaining company-provided recommendations and guidelines.

If you do need to refer to the assistant, it's generally not necessary to refer to it as "the (YOUR COMPANY NAME) product assistant" as customers are already aware they are interacting with your company. You can just call it "the product assistant."

Avoid unnecessary greetings

In most cases, users will open the product assistant from somewhere that has already introduced it. Having the assistant start with a "Welcome" or "Hello" prompt may feel like an interruption or even a step backward. It's generally best to proceed directly to a question like "What do you need help with?"

Use exclamation marks sparingly

You generally don't need exclamation marks. Save them for when it really counts, such as in warnings or making a user aware of a crucial step. Even then, they're usually not necessary.

Use contractions

Contractions make text more concise and help you sound friendly and conversational. Don't worry; it won't make you sound unprofessional.

There are some exceptional contexts in which you should avoid contractions:

• Formal or legal text such as terms of use or end user license agreements

• To emphasize words, especially the word "not"

• In warnings

Avoid abbreviations and acronyms

Abbreviations and acronyms make text shorter but often reduce clarity too much to be worth it. They can be ambiguous or confusing and prevent the user from understanding your instructions.

Examples:

• Instead of "i.e.", say "that is"

• Instead of "e.g.", say "for example"

Avoid jargon

Unless you are certain that the assistant will only be used by experts on your product that are familiar with its jargon, avoid using unexplained jargon that users may not understand.

That includes Mavenoid-specific jargon as well, such as "checkflow" or "escalation".

Avoid sequence-linking expressions

Expressions like "Then", "After that", and "when you are done with" are usually not necessary. Users will look for calls to action in your text and complete them one after another.

If you feel like you have too many calls to action in one node, consider writing a multi-step instruction or creating a step-by-step guide.

Menus and submenus

Use unicode arrows (→) to show pathways in interface menus and submenus. It's usually a good idea to set the pathway in bold or italic to help it stand out from other text.

To avoid confusion with HTML tags and URLs, don't use chevrons (>) or slashes (/) for this purpose.

Example:

• Instead of "In the robot display system, click setup, then click advanced setup to navigate to the 'Advanced setup' page", say "In the robot display system, click Setup → Advanced → Advanced setup"

One idea per sentence

Don't put too much information into one sentence. Dare to focus. It's particularly helpful for multi-step instructions when users must read and act almost simultaneously with limited short-term memory. Never describe more than two actions within one sentence.

Tell the user who's doing what

Avoid the passive voice. Make it clear to the user when they need to take action and when something will happen without them taking action.

Examples:

• Instead of "When the button has been pressed", say "When you press the button"

• Instead of "An email will be sent", say "You'll receive an email"

Node headings

Write headings as sentences without full stops

Write headings like normal sentences. Capitalize the first letter of the first word at the beginning of the sentence and leave the rest in lowercase except for proper nouns. Don't put a full stop at the end.

For question nodes, write the heading as a question

Writing the heading as a question gives the user a clear path to the answer buttons and usually saves a lot of unnecessary text. Always check that the answer texts make sense and match the question.

Example:

• Instead of "Type of battery", say "What type of battery do you want to install?"

• Instead of "Select the displayed error code", say "What error code is displayed?"

For solution nodes, write the heading as a call to action

The shift from questions to a call to action helps the user understand they may be reaching a solution soon.

Examples:

• Instead of "The drain valve may need cleaning", say "Clean the drain valve"

• Instead of "You're required to enter a valid email", say "Enter a valid email"

Node descriptions

The purpose of descriptions is to provide any additional text or images that may be needed to correctly answer questions or follow instructions.

Not every node needs a description

Don't feel obligated to add descriptions. Simple, clear, and direct questions or instructions do not need them and will just be slowed down by them.

Only add a description if you believe it's necessary for users to understand the headline and respond correctly. Make sure the description adds new information and isn't just a repetition of the information in the headline.

An image may be a great alternative, for example if it helps users find a component.

Only use images and videos that you have the right to use

Images and videos are a great way to add clarity, but make sure you have the right to use them. Never use visuals found on the internet with unknown ownership or licensing. This is an easy way to violate copyright law.

The safest bet is to find images from your existing documentation or other material or have something created for you by a technical illustrator.

Don't negate the heading in the description

If the heading makes a statement or asks a question one way, don't negate it in the description. This can easily mislead users into clicking the opposite answer from what they mean.

For example, if you have a question with the heading "Is the power on?" do not write the description as "Make sure the power is not turned off." In this case it's unclear if a "no" answer means "No, the power is not on" or "No, the power is not turned off." Keep the meaning of affirmative and negative responses consistent between the heading and description.

One question or action per node

Don't add a second question or instruction to the description beyond what is covered in the headline. Users should have no doubt about what question they are answering or instruction they are following.

If a solution requires multiple steps, consider using a step-by-step guide.

Avoid using "correctly" without explanation

Questions like "Are the cables connected correctly?" are not useful if the user does not know what the correct way is. Add or link to instructions, definitions, or diagrams that explain what "correct" means.

Be specific and give examples

General questions can be confusing. Use examples if it helps to clarify what you are asking for.

For example, "Have any liquids entered into the machine?" may be too vague if you want to know if the machine could be damaged by moisture. Instead, say this:

Has the product been exposed to moisture?

Examples:
– Liquids have been dropped onto it
– It's been exposed to rain

Warnings before dangerous steps

Put a warning directly before any dangerous step. Users mostly follow instructions in order. A warning that comes too far before a dangerous step may be forgotten, and a warning that comes after a step may be too late.

• CAUTION indicates a hazard that, if not avoided, might result in minor or moderate injury. A warning with the signal word CAUTION can also refer to a situation that could damage or destroy the product or the users' work.

• WARNING indicates a hazard that, if not avoided, could result in death or serious injury.

• DANGER indicates a hazard that, if not avoided, will result in death or serious injury.

Put the most important information first and remove unnecessary information

Keep in mind the user is trying to solve a problem as quickly as possible. Remove information that does not help the user answer a question or follow an instruction.

Additionally, expert users may just need a push in the right direction to be able to continue. Others may need a longer explanation. Put the most important actions and information in the heading and at the beginning. Additional information that only some users may need should come later.

We generally find the following order to be the best way to accomplish this:

1. Headline question/instruction

2. Image

3. Image caption (if relevant)

4. Description text

5. Answer buttons

Multi-step instructions

Put the step number and the step name in bold text. Instructions go on a new line directly below in regular text. Avoid indenting lists as it creates a jagged margin and interrupts reading and does not align with pictures.

Example:

1
Unplug the device.

2
Wait thirty seconds.

3
Plug the device back in.

If there are several images in a multi-step explanation, put the general image before the list of steps. Images relating to specific steps go below the step number/step name, but above the image caption.

Don't refer to the position of images or other content

Avoid writing things like "in the image above" or "follow the instructions below". It's usually unnecessary and can lead to confusion if images or text are rearranged in the future.

Don't make judgments on simplicity

Avoid adverbs such as "simply", "just", and "easily." The user reached out for help, so to them product probably doesn't feel all that simple right now. They may also be in a situation where seemingly simple actions may prove complicated.

Example:

• Instead of "Simply connect the cable", say "Connect the cable"

Avoid saying "please" in instructions

When you're giving instructions, you're not asking for favors. Users reach out for help, and expect you to tell them what to do. The actions aren't optional and saying "please" will make you sound overly formal and artificial.

Example:

• Instead of "Please unplug the dishwasher", say "Unplug the dishwasher"

The exception to this of course is when you are apologizing for a problem or actually asking for a favor.

Examples:

• "Please accept our apologies for the inconvenience."

• "How can we improve? Please send your feedback to [email protected]."

Asking for obvious things

Sometimes to rule out possible causes you'll need to ask the user to check things that may feel obvious. It's not always easy to ask for simple checks without coming across as patronizing or damaging your own credibility.

One helpful rule of thumb is to avoid writing such checks as their own pair of nodes. You probably don't need an entire question node for "Is the machine plugged in?" with a solution node of "Plug in the power cord." Instead, write these simple checks all together in a quick checklist, such as:

Make sure the machine is getting power.

– Check that the power cable is plugged in
– Check that the power cable isn't damaged
– Check that power lights are on