Knowledge Base Articles

The Knowledge Base section of the official product documentation contains two types of articles depending on the scenarios they support—how-to and troubleshooting.

In their essence, how-to articles instruct the user how to achieve a specific goal, while troubleshooting articles offer approaches for handling an existing problem users might come upon when working with the product.

As a logical result, the content of the two KB types is similar but they do differ both in their structure and in the way their goal and provided solutions are presented.

In This Article

• Types and Templates

  • How-To Scenarios
  • Troubleshooting Scenarios
  • CVE Scenarios

• General Requirements

  • Writing Style
  • Completeness
  • Technical Accuracy
  • Clarity
  • Sensitive User Information
  • Product and Environment Information
  • Links
  • Spelling, Layout, and Style
  • Additional References

• Balancing the Customer Context Requirements

  • Milestones
  • Metadata
  • Creating Effective Meta Tags

• Titles, Headings, and Subheadings

• Punctuation
• Takeaways

Types and Templates

How-to, troubleshooting, and CVE KB articles serve a different purpose and follow a different structure.

In This Section

• How-To Scenarios
• Troubleshooting Scenarios
• CVE Scenarios

How-To Scenarios

When creating how-to KB scenarios, note the following insights:

• How-to KB articles aim at guiding users through the specific steps for accomplishing a specific goal.
• How-to KB articles relate to questions that are not directly associated with specific issues. For example, "How to increase the performance on a server?" and "How to install a component?".
• How-to KB articles are not intended for questions such as "How to troubleshoot "xyz" error?".

The latest how-to template is available here.

Troubleshooting Scenarios

When creating troubleshooting KB scenarios, note the following insights:

• Troubleshooting KB articles aim at resolving a specific problem that users experience.
• Users look for KB troubleshooting scenarios by searching for the exact problem they have, so the articles must state that problem along with any distinctive properties in the title.
• Troubleshooting articles describes the problem, the cause of it and any possible fixes or workarounds.

The latest troubleshooting template is available here.

CVE Scenarios

CVE scenarios are created and maintained by the security team.

The latest CVE template is available here.

General Requirements

The recommended general approaches for writing a Knowledge Base (KB) article relate to the proper capturing of the presented content. Following them:

• Increases the findability of the article.
• Ensures a consistent user experience.
• Optimizes the value for users.

In This Section

• Writing Style
• Completeness
• Technical Accuracy
• Clarity
• Sensitive User Information
• Product and Environment Information
• Links
• Spelling, Layout, and Style
• Additional References

Writing Style

When you create a KB article, make sure it:

• Is short and simple.
• Is clear and concise, and does not contain unnecessary words.
• Captures the customer context, but does not include customer data or designs. For more details on how to balance between the proper capturing of the customer context and the creation of well-written KB articles, refer to the section on customer context.
• Has been checked for correct grammar and spelling.
• Is easily understood by its intended audience.
• Provides detailed instructions for resolving an issue.
• Presents all known answers or solutions to a single problem or goal.

Completeness

• Make sure that the KB article is self-sufficient—include or link all relevant information in it.
• Define or reference all non-obvious terms and acronyms in the article.
• Bring the main thought to completion. For example, state the problem, its cause, and, most importantly, the fix that works in the specific environment.
• Reference or at least mention in the article all additional data that helped in developing the solution.

Technical Accuracy

• Provide technically sound and valid information.
• Make sure that the suggested approach or solution works in the specific environment.
• Do not include untrue or invalidated statements.
• Make sure that the code snippets work as expected in the specific environment. Errors are not allowed.

Clarity

The KB article must be logical. Avoid ambiguous, confusing, or vague statements.

Sensitive User Information

The KB article must not include any sensitive user information.

Product and Environment Information

Make sure that the KB article lists enough information regarding the product or the environment that are used and in which the described scenario takes place.

Links

• Make sure all cited links in the article work as expected and are not broken.
• Ensure that the article links to all online resources that are mentioned in it.

Spelling, Layout, and Style

• No spelling errors are allowed.
• No grammatical errors are allowed.
• Use bulleted or numbered lists in accordance with the guidelines in the Style Guide article on lists.
• Use pronouns in accordance with the guidelines in the Style Guide article on pronouns.

Additional References

It is not mandatory to refer to additional resources in the KB articles when, for example, the question or problem relate to a new functionality and is not documented anywhere.

Balancing the Customer Context Requirements

Generally, we use "customer context" to refer to the user input when they search for a specific issue, problem, or a question submitted in a support case. By capturing the customer context in a KB article, we aim to increase its organic findability in search engines, such as Google, and enable other users to discover when they search for the same issue, problem, or question.

In short, the common approach to create easily retrievable KB articles is to try to include as much of the customer wording as possible in the relevant metadata and in the body of the KB article (title, description of the scenario, solution approach).

In This Section

• Milestones
• Metadata
• Creating Effective Meta Tags

Milestones

The implementation of the customer context must not happen at the cost of bad grammar, wrong spelling, or scarce or incomprehensible information.

The strict adhering to the exact customer log is not recommended because of:

• Grammar and spelling—From a user point of view, the KB sections are part of the official product documentation.

  Therefore, the content of each KB article must be grammar- and spelling-wise correct.

• Understandability—The wording a customer has used to log an issue or search for a solution may greatly differ from what another user will understand from the logic of that same input.

  Therefore, provide human-readable content even if you have to change the form of the verb or other main words when paraphrasing. For example, if you have to paraphrase, it is OK to change "render" to "rendering/rendered/not rendered/will be rendered/renders".

• Context—The context of the scenario, its description, or solution may be absolutely clear to you and to the customer who has logged the issue, but for the rest of the users who will need to use the KB article, that context may not be so easy to grasp because of varying technical or language competences.

  Therefore, building on top of the customer log, try to be as descriptive as possible and provide additional information so that users are able to immediately decide if this KB article solves their problem or not.

Metadata

In terms of the KB metadata, the elements considered to count most are the following:

• title—Use a combination of the main problem and, if applicable, the key environment by applying the customer words as closely as possible.
• description—The description content is what search engines usually show in the search results. As search engines truncate the description after a specific number of characters, try to come up with a brief overview of the KB article. Exclude unnecessary phrases like "This article contains ..." and capture the customer context instead by expressing complete thoughts about the issue the same way as customers have asked or searched for it.
• meta_title OR page_title—Use different title from what you used in title so that you cover more key words and improve the findability of the resource by search engines. Capturing the way users ask about the issue is key here. Note that meta_title replaced page_title in documentations running on the docs-builder platform.

For more information on creating effective meta_title and other meta tags, refer to the article on metadata.

Titles, Headings, and Subheadings

When you define titles for how-to instructions, adhere to the following recommendations:

• Use the -ing form to make it clear from the beginning that the article suggests a how-to approach. For example, Aligning Range Bar and Column Chart Series is equivalent to How to Align Range Bar and Column Series but is shorter and easier to grasp.
• Use upper case in accordance with the capitalization rules for defining titles.

When you define titles for troubleshooting scenarios, adhere to the following recommendations:

• Use a whole sentence that states the problem—for example, Dates Are Treated As Strings during Grid Data Operations.
• Use upper case in accordance with the capitalization rules for defining titles.
• Use appropriate punctuation as the title is a sentence.

Regarding the discussed customer context approach in this article, here are some suggestions for creating meaningful KB titles based on the customer context:

• If the customer log is How to serilize (spelling!) RadSpreadsheet Workbook with images it is perfectly OK to set the KB title to Serializing RadSpreadsheet Workbooks with/Containing Images.
• If the customer log is Cascading ComboBoxes in Grid with BatchEdit, make it Implementing/Handling Cascading ComboBoxes in Batch-Edit Mode Grids, or similar.
• If the customer searched for Nuget Error in Maui Check Tool, beautify it as The MAUI Check Tool Throws a NuGet Error while Running.
  

Punctuation

For the body of a KB article, follow the common rules in the Punctuation Style Guide topic.

As for the KB titles and headings, we often doubt whether at all to use punctuation. The general rule is that we have to use any punctuation which is required by the title, heading, or subheading. In most cases, such titles, headings, and subheadings are complete sentences and might require additional punctuation for clarity. However, do not use a full stop in the end unless having more than one sentence as a title, heading, or subheading.

Takeaways

The takeaways to apply to all parts of the KB articles, including their metadata, title, body, are:

• Keep in mind the wording of the customer log or search.
• Review their spelling and grammar.
• Express complete thoughts and ideas when providing additional information.
• Use common sense—from deciding what to keep and what to change from the wording of the logged issue, through what context and title to provide, to what punctuation to use.