Using documentation templates to improve your writing process

Knowledge base templates are a handy way to be more productive and consistent with your documentation. The type of template you need depends on what you want to use your templates to achieve.

In our case, we’re talking about templates for your knowledge base articles, to ensure consistency across your documentation. It’s easy to come across as ramshackle and haphazard in your documentation if you don’t employ templates, which doesn’t make for the best User Experience.

Knowledge base templates are especially useful if you have a number of contributors producing your documentation, need to produce a lot of documentation, or your documentation might be changing hands in the future. Maybe you tick the boxes for a number of these factors.

What is a knowledge base article?

First, it helps to define what we mean by knowledge base article. Kayako defines a knowledge base article as:

“A knowledge base article is a comprehensive overview of the different aspects of your product or service. It’s detailed, informational, and may include step-by-step instructions to teach the customer how to accomplish a task.”

This means knowledge base articles particularly benefit from templates because they are written to help users. This writing process can be standardized to a large extent, and knowledge base articles should be as clear as possible.

There is not much room for creative storytelling in your documentation – the writing is about users, rather than the author.

KnowledgeOwl article templates

In our knowledge base software KnowledgeOwl, you have the ability to create knowledge base articles in the WYSIWYG Content Management System (CMS). You can either create a brand new article, or duplicate an existing article.

KnowledgeOwl article templates are just like regular articles, but you create an article using an existing template. The article template is saved within the body of the article. Copying your saved article containing your template basically just copies everything you have in the template's article body into the the new article created from it.

Our Support Sorceress Kate Mueller was previously a KnowledgeOwl customer before she worked with us. At her old company she used the templates in two ways:

• Keeping consistent categories of content
• Using them as style guides for documentation

The templates were useful for both making sure content was always written in the same format, and that writers followed the same style conventions for every article.

Consistent categories of content

For categories of content that always had a consistent structure, Kate set up a template containing headings and subheadings. She also included some placeholder text in paragraphs that might describe where to get content from, or highlighted the portions that people needed to fill in.

For example, some text within her templates might have been, "Copy the product description from System X and paste it here; copy the Reference Number from the packing slip and paste it here.”

Style guide

Kate’s company also treated more general templates like style guides. They contained sample text, and headings and subheadings. They included other elements with descriptions of when and how to use those elements.

For example, they had a snippet to create an article table of contents. The snippet had a note telling folks to remove the snippet if the article had fewer than 3 headings or subheadings. This meant the template was a self-documenting guide rather than what you might consider a “true” template.

The purpose of this template was to guarantee consistent styling across all new articles.

Elements of a good template

As Kate has already touched upon, use templates to tell your writers how to:

• How to structure a table of contents
• What to include in your intro
• What to include in your conclusion
• Important terminology
• How to interlink
• How to write your headings
• When to use numbered lists
• When to use bullet point lists

There are some common elements to look out for when writing your templates. The elements of a good template are:

• Well-structured titles and subtitles (sentence or title case) containing keywords
• Ideal length of sections and subsections (one section no longer than around 100 words)
• Table of contents listing out the steps contained in your article
• Sample text for how to write your documentation
• Introduction containing summary of the content with quick solution
• Bullet points for step by step instructions or numbered list
• Call-outs for important information or alerts and an example of what these might be
• How to interlink content using the subject of the article as the link anchor text
• Instructions on using Hemingway or Grammarly to check your content readability
• Examples of where to use case studies for your how-tos

Your templates will be unique to your company, but make sure to keep them as simple as possible. Trying to cram in too many instructions runs the risk of making your template confusing, and discouraging people from using it. Trust your writers to interpret your instructions rather than being overly authoritative.

Feel free to come up with a number of templates for different types of documentation. For example, a Getting Started tutorial would differ significantly from a reference guide.

Template example

Kate has created some fantastic templates for our KnowledgeOwl documentation. For example, there is the how-to template:

Kate's general documentation template

Notice Kate’s use of Heading 2 for major topics, and Heading 3 for subtopics. She recommends you:

• Always use numbered lists for step-by-step instructions
• Use bullet points for other types of lists 
• Indent your sample code and screenshots within list items if they refer to the list item
• Make sure you use brand colours for any arrows or shapes used in your screenshots

KnowledgeOwl makes it quite easy to create your own templates. To create a template in KnowledgeOwl, create a new article containing examples of the elements that every new article should include.

Add a new article from a template in KnowledgeOwl

Save that article and label it as ‘TEMPLATE’, including instructions to COPY your template instead of saving a new article over the contents.

Benefits of using templates

Using templates for your articles helps reduce users’ cognitive load and improve what they can hold in their short-term memory. If they know what to expect from your articles each time, this helps them form an accurate mental model of your knowledge base that they can use anytime they self-serve. You are helping your novice users to become experts.

Templates also save time so you don’t have to write everything from scratch when creating a new article. They ensure your articles are comprehensive, and you don’t miss important elements like interlinking or subheadings. It helps prevent mistakes by signposting article writers towards useful resources, or reminding them of important rules to follow.

In essence, you create a workflow for your documentation with templates that becomes a repeatable, standardized process.

Your turn to rock!

Using a knowledge base article template is crucial to your documentation efforts. It helps you standardize your content and create a consistent style that makes your documentation more professional. It makes producing new documentation quicker and easier.

Do you have a sample template you've been working with that you'd like to tell us about? We’d love to hear your ideas!

KnowledgeOwl is our very own knowledge base software. Take it for a free spin.