Knowledge Base Content Best Practices

Objective: Provide customers with Best practices/Recommendations to author & maintain Knowledge Content in Knowledge Bases and Document Repositories that can be leveraged by Support agents and Knowledge Analysis Solutions

General Knowledge Base Guidelines

1. Use Knowledge Bases from the System of Record as preferred option (such as a ServiceNow knowledge base or JIRA Confluence)

2. Web/HTML & Wiki, Confluence or SharePoint like knowledge repositories should be next preferred option

3. If knowledge bases and knowledge repositories are not available, then use file formats such as HTML, PDF

Note: There are known challenges with PDF format parsing that includes limitations on content extraction from PDF on images, multimedia, tables etc.

1. Microsoft Office Documents such as Word, PowerPoint and Excel are not preferred for Help Desk & Customer Support Solutions

Knowledge Content Guidelines

• Leverage KCS v6 methodology for techniques on content creation from title, section, sub-section, paragraph of knowledge document

• Use Standard KB Templates that are available in Knowledge Bases such as FAQ, How-to, Issue-Resolution available in Service

• Ensure all Meta-data fields related to Knowledge Articles are captured. This includes – Category, Article Type etc.

• Ensure Knowledge Article Titles are appropriately capturing Symptoms and not just Solutions. This helps in improving search accuracy in finding relevant content and articles.

• Ensure Article content is simple and consistent:

  • Use plain English: Avoid big words. Use less syllables for a higher impact.

  • Define Acronyms: Acronyms are not intuitive or easy to follow. The first time you use an acronym in an article, spell it out and follow it with the acronym in parentheses. (E.g., Virtual Private Network (VPN)). The next time you use it in the article just use the acronym.

  • Avoid Jargon: Not everyone understands the jargon used. Keep content simple.

  • Use Active Verbs: In your sentences use the active voice not passive. Example:

    • - passive: The files will be deleted by clicking on Delete.

    • - active: Click Delete to delete files.

Knowledge Content Formatting

• Use Single Column Layout for formatting documents

• Use headings and subheadings to distinguish sections (use H1, H2, H3 tags) with consistent branding across pages

• Ensure images and video content can be rendered in most browsers

• Avoid using nested lists within documents

Example: Zendesk Knowledge Article Section and Subsection formatting with Aisera’s Conversational AI result below.