SUMMARY

This article will outline the different types of articles we are developing throughout the DM and CLINIC knowledge base. You will also find a definition section below that explains the common terms we will use.

Article Type: Tutorial

Tutorials are step-by-step guides that are focused on introducing one topic, or a small group of closely related topics. It’s learning-oriented and allows the beginner user to get started. Think of a tutorial as a lesson that teaches the user how to do something.

Include:

Include a summary of what the article contains at the beginning of your tutorial
Tell your user what they can expect to learn, and what they prerequisites they will need to complete the tutorial
Focus on offering a way to get your user started

Formatting Tips

Try to arrange the necessary steps in progressive order of difficulty, from easy to hard.
Include only the steps your user needs to take to complete the task
Include only concrete steps in your tutorial, and avoid abstract concepts that don’t relate to practical learning.
Control the length of your tutorial steps – keep them concise but not abrupt.

Article Type: How-To

A how-to guide seems similar to a tutorial, but is actually aimed at solving a specific problem or issue with the software. How-to guides are goal-oriented and presented as a series of steps, and can be seen more as a troubleshooting type of content. These articles require some pre-existing knowledge of the subject matter from the user, and are designed to achieve a specific end.

Include:

Choose a descriptive name for your guide that tells the user exactly what the guide intends to solve
Format your how-to guide as a list of ordered steps (1, 2, 3)
Summarise the solution at the beginning of the guide so more experienced users can skip to the important part
Focus on the results of achieving a practical goal with your software, and solve a specific problem that has been troubling the user

Formatting Tips

Write your guide in full sentences with proper grammar and punctuation
Include call-outs within the body text to highlight necessary information – for example, how performing a particular action will affect the system
Avoid explaining “conceptual information” by linking to explanations elsewhere instead
Leave out any information that is unnecessary for completing the task

Article Type: Explanation

Another type of documentation you may need to use in your knowledge base is an explanation. This type of documentation may not even have its own section, but could be interspersed through the rest of your content. It provides crucial know-what for your users regarding your software.

Include:

Provide as much context as you need to and explain the “why”
Don’t instruct the user or include any technical reference
Use this type of content to expand user understanding of the software as a whole
Use simple language that anyone can understand

Article Type: Reference Guide

A reference guide is an information-oriented technical document that describes the software, or any related aspect of the software that your user needs to know about. It could include reference material like a glossary of terms used in your knowledge base, or API and webhooks documentation that includes the main interfaces/properties/methods for your software. You could list technical specifications for your software, current integrations, and so on.

Include:

Aim for consistency in your structure, tone, and format
Describe only the relevant technical component, and avoid instructing or explaining
Use a straightforward and matter-of-fact tone
Check rigorously for accuracy

Terminology

Summary: This is the opening section of every knowledge base article. It is the executive summary of what the article is going to achieve

Section: This is each of the parts of the article. When there is a different topic or change of focus, it is to have a new section.

Anchor: This is an indexable section of the article that will be used to hyperlink from the top of the article right to that section.

Source: This is a button in the builder that will switch the editor from a visual builder to a code builder. You will only need to use this button to embed a youtube video