When writing articles for your knowledge base (KB), follow the guidelines provided below in order to write articles that enable the Moveworks bot to best answer user questions in chat. This means writing articles that “snippetize” well and follow basic KB article best practices.

Snippetizing

For longer articles, Moveworks divides the article into multiple snippets that can be used to answer individual questions. We call this snippetizing - showing the relevant snippet in bot. Snippets are brief excerpts of information created from sections of a larger article.

When a user asks the bot a question, the Moveworks bot then searches across all articles to find the most relevant snippets.

Snippet character display limits

The maximum number of characters that can be shown in a snippet is 500 characters. The title of the article does not count towards the maximum number of characters.

💡

Note: A snippet is not always exactly 500 characters. Snippets end at the first space after 500 characters, this is done so that the last word in a snippet is not cut off.

How does Snippetization work?

When Moveworks “snippetizes” an article, the bot analyzes an article’s structure in order to break it up into snippets to be served to users. For each article, one level of header is used to divide an article into sections, these sections then make up a snippet. Many factors go into how the bot decides which level of header to use.

When a bot analyzes an article, it sees if the article is an FAQ-style article or a non-FAQ-style article. FAQ-style articles are articles where 75% or more of the headers are questions. If the article is an FAQ-style article, the bot will use the highest level of header in that article that appears the most and are formatted as questions to create snippets.

If the article is not an FAQ-style article the bot will use the highest level of header that appears twice or more throughout the article to create snippets.

And if no header appears more than once, the bot will take the whole article and treat it as a snippet.

Snippetization Best Practices

For best results, write articles which snippetize well by following these guidelines:

1. Where possible, divide your article into sections.
2. Title each section using a clear, specific heading.
3. Ideally, ensure each section can be understood independent of the rest of the article when served as a snippet.
4. If your article contains a set of questions, it is recommended to structure it with each question in a header style, as opposed to using paragraph style and bolding or italicizing the question. See below for more details.

FAQ-style Articles

FAQ-style are articles structured as a list of questions commonly posed by employees around a topic. The bot is able to identify this style of article by looking for articles that contain multiple headings that end with a “?”, and if the article contains at least four such headings.

When writing FAQ articles follow these guidelines:

• Use Header 1 (H1) for the top level questions.
• Each H1 should have a “?” at the end to make it identifiable as a set of FAQs.
• Header 2s (H2) should be used as needed for sub-topics within H1s.

Non-FAQ Articles

Non-FAQ Style Articles include troubleshooting articles, how-to articles, policy articles, etc. When writing Non-FAQ style articles follow these guidelines:

• Use a minimum of two H1s if you would like that to be the level at which snippetization occurs.

Knowledge Base Best Practices

Vary Your Article Types

A strong knowledge base contains a rich mix of article types, focusing on single topics, and formatted in a manner users are familiar with. This helps users self-service a solution, by managing their expectations, so they will know what to look for when being linked a KB article by the Moveworks bot. For example, with a well organized KB, when a user asks a question on how to do something, they can expect to receive a how-to KB article, formatted into numbered steps that the user will know to look for and follow.

How to determine what kind of article you need?

• Troubleshooting articles: Use this format for articles that focus on solving a specific problem or issue.
• Q&A type articles: Use this format for articles that describe routine tasks (e.g. setting up software or applications, creating log-in credentials for the first time).
• How-to articles: Use this format for shorter articles that can be answered in one or two lines. This is also the ideal format for temporary articles (e.g. updates about a server being down).
• Policy articles: Use this format for articles that address office protocols, such as HR, legal, payroll, or facilities-related topics.

Troubleshooting articles

• Steps are formatted into a bulleted list, which is easier to read than paragraphs

📘

Tip: Numbers for steps to be done in sequence; bullets for list of actions that can be taken or completed in any order.

• There are nested steps (see bottom three bullets), but step nesting only goes two levels deep (first level is the bullets, second level is the letters).
• The article includes information at the bottom allowing for escalation should the troubleshooting steps listed fail to resolve the issue. This could also include a link to open a ticket or IT issue, email or phone contact info for the relevant person/department, etc.

Q&A type articles

• Each header should address a specific task or question.
• If possible, limit lengthy paragraphs or blocks of text before numbered steps.

How-to articles

• Includes instructions for multiple operating systems.
• Steps are a numbered list, which makes for proven easier/quicker reading than paragraph format.
• Subtasks which not all users may be familiar with (such as pulling up the “Run” command prompt) are explained within the article as well.

Policy articles

• “Policy” is mentioned within the title. When articles are ingested by the bot, this helps the bot identify this article as a policy topic.
• Acronyms such as PTO are written out in the title of the article for clarity.
• Where further information is required from the customer organization, there is a placeholder in bold, red font that describes the type of information needed. This makes it easier for customers to skim through our articles and fill in org-specific information where necessary.

Clean, Consistent Formatting for each article type

The best knowledge articles have consistent formatting that take advantage of Moveworks’ best practices (outlined in the section “How to write good knowledge base articles?” below). Areas of focus include header styles, link styles, table formats, and image formatting. Using consistent formatting not only makes it easier for the bot to understand the content, but also provides users with a consistent and reliable experience. Many knowledge base platforms support “templates”, it’s often useful to come up with a standard template for each of the article types you will be writing to ensure that by using the template the Moveworks bot will parse your content optimally.

Employee-Friendly Terminology

Articles perform better when written using language a user would likely use, rather than technology or industry jargon. What may seem like a common phrasing for the support team, may be foreign to how users refer to the issue or topic. Updating terminology to be customer friendly help improves search results, making it easier for users to self-serve answers to their questions within the Moveworks bot.

Before:

IAM App Request SOP

After:

How to request a new application in Okta?

Knowledge Base Articles Best Practices

1. Use consistent proper headers throughout your articles

When formatting your articles use the built-in header styles in your knowledge base. For example, Confluence uses “Heading 1,” “Heading 2,” and “Heading 3” style headers.

Moveworks recommends only using three heading levels (H1, H2, and H3). If you have deeper nesting in articles, consider breaking them into smaller articles.

Refrain from using a level-2 or level-3 heading style as the top-level heading style. Also do not bold and use large font text as headers.

When your articles do not adhere to the built-in header style, or uses unconventional headers, the bot has a hard time “snippetzing” and formatting your KBs for easy viewing in chat.

🚧

Note: Do not insert hyperlinks into headings. When the bot “snippetizes” the article and serves it to the user, it will not be able to carry over these hyperlinks.

2. Follow Hyperlink best practices

Avoid placing too many links inside your article text. As a rule of thumb, use links for the following use cases:

• Too much text to include in KB: When you can't fit the referenced information into the page you're writing
• Text is not relevant to all users: When you need to point to information most readers won't need, but a few might find useful.
• Call to action link: When including a call to action to visit another URL/website. Try to keep the link text (the part the reader sees) as short as possible while clearly spelling out what the target of the link is.
  • “Click here to sign up for a new phone plan on the AT&T Portal”

Make sure the URL in the link is one that's accessible to everyone who might see this answer in chat. Typically this includes all of your employees and contractors. If it is expected that users will not be able to view the link, make a note of that in the document.

e.g: If you are a FTE employee, you can find more information here.

Readers prefer to see all the steps in the text they're already reading.

📘

Note: In order for links to render properly, use the built in linking system in your knowledge base.

3. Avoid Using Tables and Nested Lists

Tables are very useful for conveying values and options to the reader, but you should avoid using them for formatting purposes e.g: to align text on the page. Instead leverage headers, bullets, dashes, and other plain text formatting methods.

When Moveworks reads text, it expects to see headings and body text as normal paragraphs. Moveworks ingests tables with limited formatting preserved, typically by processing the table into a CSV. The bot is currently unable to surface content from tables in-chat. Usually content from tables can be snippetized into its own subsections and more accurately be presented.

If you have, for example, a series of paragraphs in a table, with the left column containing headings and the right column containing the body text, you should consider replacing the table with a series of headings and body text paragraphs.

Nested Lists

When using bulleted or numbered lists in your knowledge articles, avoid creating nested lists, or lists within lists. Due to limitations of chat platforms regarding bot messages, the bot will not be able to serve these lists with the original formatting in-chat. The nested list will be flattened and the list items will all appear on the same level.

4. Best practices for Rich Content (Images, Videos, PDFs, PPT, DOCX, iframes)

Images, videos or other visuals can be useful for helping readers understand concepts quickly. Because Moveworks relies on text and not images to understand articles, it's important that images are accompanied by supporting text that conveys the key information in the article. This supporting text provides Moveworks algorithms with relevancy signal around the image, PDF, or other file type. Employees can then easily identify that a given article is relevant, and click through to view the original article with its images.

PDF Guidelines:

• Moveworks does not ingest the content within a PDF directly. The bot can embed PDFs found within your KB in its reply to user questions. So when a user asks for a guide or article that is in the form of a PDF, the bot can link them to the location of the PDF in your KB.

Images Guidelines:

• Do not use images to provide text. Moveworks cannot read text that's embedded in your images (no OCR), so avoid such text if you expect it to be critical to resolving the user’s issue.
• If you do have important text embedded in images, it's a best practice to repeat that text as body text on the page.
  

Include Location in title for Location-based Personalization

If content is location specific, whether that’s by region (EMEA, APAC) or country (Switzerland, India, Australia), you must include the location in the title of your article for the bot’s location-based personalization ranking boost to take effect.

There’s no specific format (hyphens, parentheses, brackets) necessary for this to work — but you may want standardize your articles with a consistent format for referencing a location in your articles to make it easier for your employees to read.

An article that's useful only for employees in the Austin office should clearly indicate that in the article’s title. For example, "How do I connect to the printers in the Austin office?"

If a user in the Austin office asks “How do I connect to the printers?”, the above article will be preferentially displayed over the printer help articles for other offices. Additionally, if a user in the San Francisco office specifically asks for the location by name, for example “How do I connect to the printers in the Austin office?”, the Austin content will show up over will be ranked higher than other relevant articles about printers.

Content

1. Each article should make it clear in which situations it's useful. For example, if you are writing an article that only applies to Mac OS users, you need to clearly indicate that in the title of the article, or in a sub header within the article. Likewise, an article that's useful only for employees in the Austin office should show that in its title, for example, "How do I connect to the printers in the Austin office?"
2. Do not rely on article hierarchies to provide context. Some knowledge bases allow you to save the articles in a hierarchy with buckets, for example, "Austin office." Do not rely on this hierarchy to tell the reader when the article is useful. Instead, place those context hints in the title or body of the article.
3. Lastly, get to the content! Once you write a clear title, avoid writing intro content like “This article will explain to you the 10 steps it takes to solve your problem.” This is fluff that takes up space in the article snippet and does not help with search relevance.
   

How to accelerate bot learning?

In-chat

• When interacting with the bot in-chat provide feedback about bot responses - this signals for autonomous updates over a medium- to long-term time frame.

By filing a support ticket

• Provide highly specific entities, such as naming schemes, which do not exist outside your organization. For example, if you've white-labeled your intranet platform, or if you've developed any in-house applications, benefits programs, or resources that don't exist outside of your organization.
• Provide customer-specific informal terms, abbreviations, or colloquialisms that are used by users but not necessarily present in knowledge base articles.
• Proactively coordinate with the customer success team to incorporate relevant details about organizational changes and major updates to the bot.
• Prioritize a specific knowledge base article or form among competing confidence options based on business need (i.e. incorporating customer preference to adjust ML-driven recommendations).