Write Docs That Work Well With Scout

Scout works best when your Docs are clear, consistent, and easy to follow. If Scout misses details or uses the wrong context, you can update your articles and refine results over time.

This guide shares some practical writing tips that can help Scout use your Docs more accurately.

Write Clear Text Instructions

Images and videos are helpful visual guides for people reading your Docs, but they should support your instructions, not replace them. While this is true even when writing just for your customers, it's extra important for Scout. If your steps are only shown in a screenshot or video without written context, Scout will miss important details.

What to aim for:

• Add a short sentence before (or after) an image that explains what’s happening.
• If an image shows a UI detail that matters (a setting name, a button label, an option), include that detail in the text too.

Use Plain Language for First-Time Readers

Write your Docs for someone who is learning about your organization, product, or services for the first time. This helps customers move faster, and it gives Scout clearer source material to work from

• Use short sentences.
• Prefer common words over technical language that a new customer might not know or provide an explanation the first time you use technical language in an article.
• Define any terms that a new reader might not know.

If you want a general set of writing principles to use as a checklist, Write the Docs (a wonderful community full of resources for documentation needs) has some great guidance here: Principles of Great Content.

Prefer Active Voice

Active voice helps customers understand what to do, and it can make your instructions easier for AI to interpret.

Active voice examples:

• “Select Save.”
• “Turn on Notifications.”
• “Choose Email as the delivery method.”

What to avoid:

• “Notifications should be turned on.”
• “The form can be submitted.”

Helpful resources:

• Google Technical Writing: Active Voice
• KnowledgeOwl: Why Active Voice Matters in Docs

Use Step-by-Step Instructions for Tasks

When a customer needs to complete an action, step-by-step instructions are usually the clearest format. They also reduce the chance that Scout will rewrite your process in a way that changes the meaning.

Recommended:

1. Click Button name.
2. Select Setting name.
3. Click Save.
4. Refresh the page.

Less clear:

• “Click the button, then click save, then refresh the page.”

Review Results and Improve Over Time

It can take some experimentation to get the best results. Some best practices to help Scout and Docs stay up to date:

• Review Scout conversations to see where responses fall short. Head to Reports > Scout to find your history there.
• Decide if what's needed is a Text source, an Exclusion, or an update to Docs.
• Update the relevant Docs article to add missing context, clarify terms, or convert a paragraph into steps.

Over time, small updates will make Scout more consistent and reduce repeat questions.