Tips for article writing

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” or “chunk” well and follow basic KB article best practices and also making them easy to understand for your users.

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

Read more about how we create chunks here.

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.

Format text with plain text formatting tools instead of tables

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. Content from tables can be snippetized into its own subsections and used for answering relevant questions.

IMPORTANT: Moveworks currently does not support tables with headers that span multiple columns. Such tables will not be ingested.

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 your 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.

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?”

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.