Knowledge Base Content Best Practices

This guide outlines recommended methods for creating and maintaining high-quality content across knowledge bases and document repositories. Following these best practices ensures that support agents and knowledge analysis solutions can efficiently find and utilize the information they need.

Knowledge Source Preference

When selecting a knowledge source, prioritize formats that offer the best structure, searchability, and compatibility with automated systems. The following order of preference applies:

1. Systems of Record (SORs): Use dedicated knowledge management platforms such as ServiceNow or Jira as the primary source of truth. These systems offer structured content, version control, and native integrations that make knowledge retrieval more reliable and consistent.

2. Web-Based and Wiki-Style Repositories: Web or HTML-based repositories, such as Confluence spaces, SharePoint sites, or internal wikis, are the next best option. These formats support structured content are are generally well-suited for automated parsing and indexing.

3. Static File Formats (HTML, PDF): Structured file formats such as HTML or PDF is the next best option.

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

4. Unstructured Documents: Plain text files, Microsoft Word documents, and other unstructured formats should only be used as a last resort. Without consistent formatting, headings, or metadata, these documents are significantly harder to parse, index, and retrieve accurately, and may produce unreliable results in automated knowledge analysis workflows.

Content Creation Guidelines

Structure and Templates

• Follow KCS v6 Methodology: Apply Knowledge-Centered Service (KCS) v6 principles when structuring knowledge content. This methodology provides proven techniques for organizing articles at every level ensuring content is consistent, findable, and easy to maintain over time.

• Use Standard Knowledge Base Templates: Where available, use the standardized templates provided within your knowledge base platform. common template types include:

  1. FAQ for frequently asked questions and quick answers.

  2. How-To guides for step-by-step instructional content.

  3. Issue-Resolution for troubleshooting known problems and their solutions.

• Capture Metadata: Every knowledge article should have its metadata fields fully completed before publishing. At a minimum this includes fields such as Category and Article Types. Complete metadata improves discoverability and ensures articles are correctly routed and surfaced in search results.

• Write Title That Reflect Symptoms, Not Just Solutions: Article titles should describe the problem or symptom a user is experiencing, not just the resolution. For example, "Unable to connect to VPN" is more searchable than "VPN Configuration Steps." This approach significantly improves search accuracy by matching the language users naturally use when seeking help.

Writing Style

• Keep Language Simple and Plain: Write in plain English. Favor shorter, simpler words over complex ones. Fewer syllables generally means higher clarity and impact. Avoid unnecessary complexity that slow down a reader trying to solve a problem quickly.

• Define Acronyms on First Use: Acronyms are not universally understood. The first time an acronym appears in an article, spell it out in full followed by the acronym in parentheses. After the acronym has been spelled out, the acronym alone is sufficient.

• Avoid Technical Jargon: Technical jargon can alienate readers who are unfamiliar with internal terminology. Keep content accessible to the broadest possible audience by using everyday language wherever possible.

• Use Active Voice: Write sentences in the active voice to make instructions clearer and more direct. passive constructions can obscure who is doing what.

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

  • Active: Select Delete to remove the files.

Content Formatting Guidelines

Well formatted articles are easier to read, easier to maintain, and more reliably parsed by automated systems. Apply the following formatting standards consistently across all knowledge content.

• Use a Single-Column Layout: Single-column layouts are easier to read, more mobile-friendly, and less likely to cause rendering issues across different platforms and knowledge base interfaces. Avoid multi-column designs that can break when content is indexed or displayed in different environments.

• Use Headings and Subheadings Consistently: Structure articles using a clear heading hierarchy. Consistent use of heading levels improves readability, aids navigation, and ensures a uniform look and feel across all articles.

• Ensure Media Renders Across Browsers: Any images or video content embedded in an article should be verified to render correctly in all major browsers. Avoid proprietary formats or plugins that may not be universally supported. Use widely compatible formats such as PNG or JPEG for images and MP4 for video.

• Avod Nested Lists: Deeply nested lists add visual complexity and can be difficult to follow. If content feels like it needs multiple levels of nesting, consider restructuring it using headings and sub-sections instead. A flat, well-organized structure is almost always easier to read and maintain.