Creating a Perfect Style Guide for Your SaaS Knowledge Base

The landscape of modern business is rapidly changing, especially regarding the use of technology. While it was once commonplace to make a phone call to the tech team, users of the latest SaaS knowledge bases are after comprehensive documentation to help them use your software on their own. Knowledge bases become the first port of call when your users need help, and are especially important for feeding content into AI tools like chatbots, which are becoming increasingly popular.

So you’ve got the content, but you’re unsure how to present it. This is exactly where a knowledge base style guide comes in. You know your users expect an excellent user experience, or they’re going to grow frustrated with your self-service content. A style guide is an internal document for the contributors of your SaaS knowledge base.

Knowledge bases can have thousands of pages. You’ve got many content contributors, often from multiple teams and based in more than one location. If you’re not careful, your SaaS knowledge base can end up a mess of different styles. We’re trying to prevent this with a knowledge base style guide.

Think of a style guide as instructions for writing. They’re not hard and fast rules, but rather a guide for how content should be created, so your contributors can make their own choices but have access to consistent advice about how they should approach components of the writing process.

Importance of a Style Guide in Knowledge Base

As we’ve mentioned, a style guide is crucial for building a knowledge base. If users encounter articles written in different styles, with inconsistent formatting, conflicting terminology, and other errors, they’ll lose trust in your knowledge base.

Knowledge bases often contain complex information relating to your SaaS product. Dense information is easier to understand if your knowledge base is written in a consistent style with articles following the same conventions, rather than a mixture of different voices that distract from the actual content.

A style guide helps contribute to the overall experience of using your knowledge base and ensures that your organization speaks with one voice. No matter who writes an article, it always sounds like it comes from the same brand.

Now we’ll move on to exactly how to write your knowledge base style guide, with tips on what to include.

Section 1: Article Content

1.1 Choosing Article Topics

There are many potential articles that your writers can choose from. Offering guidance on the best way to choose article topics should be part of your style guide. For example, you could instruct writers to look at empty search terms in the knowledge base, which is easy to do in Document360. You could ask them to look at popular ticket topics in the help desk, or you can systematically document a new feature.

1.2 Crafting Effective Titles

Titles are the first thing users see when they land on your content, and they are also searched by your AI search (available in Document360). These titles should be short and contain the keyword somewhere near the beginning of the title. Titles are also important for search engines (covered later).

1.3 Using Labels and Tags

Offer consistent advice on how to use labels and tags. In your knowledge base, it will be possible to tag your content so that it can be grouped logically, using words and phrases that relate to the body of the article. This enables more users to find the needed help without using the exact search terms.

1.4 Writing Clear Summaries

Did you know that AI can write article summaries for you? This is certainly possible in Document360. Users may not want to read the entire body of an article, and article summaries save them time by providing a condensed version of the content. Set rules for how long your article summaries should be and how writers should approach writing the summary, or at least check whether AI has matched the right conditions.

1.5 Adding and Formatting Links

The way that writers use links in their articles can vary drastically, so you’ll want to provide consistent advice for how to add and format them. You’ll likely want to specify that links should be added to keywords and colored and underlined to account for the visual needs of different users.

1.6 Using Notes, Tips, and Warnings

Offer guidance on how to use notes, tips, and warnings interspersed throughout the body of your content, so it’s clear to your users that they should pay attention to these bits of information. Let writers know what color they should be and when they should be used, making it clear that there is an appropriate situation for each.

Section 2: Structuring and Formatting

2.1 Clear Headings & Subheadings

Include a section on knowledge base formatting. Breaking up your content is vital, and that’s where you’ll instruct writers when to use headings and subheadings. These will be H1, H2, and H3, so let writers know the formatting options and how to write an ideal heading (saving a template in your style guide is ideal). Headings should clearly outline the section’s content and use keywords that can be indexed.

2.2 Short Paragraphs & Bullet Points

To make your content even more readable, let your writers know how to use short paragraphs and bullet points to break up long-winded chunks of text. Instruct writers to only write paragraphs that are two or three sentences long, and use bullet points whenever they are writing a list.

2.3 Step-by-Step Instructions

It’s likely in your SaaS knowledge base that you’ll be writing about step-by-step instructions to help your readers troubleshoot common problems. Ask writers to use numbered lists to help users follow along and understand where they are going wrong in the process, and restrict each step to as few sentences as possible to increase comprehensibility. 

2.4 Bold for Key Terms

It’s also advisable to write key terms in bold, and in this way, you can use formatting to draw attention to important words. Make sure you emphasize using bold versus italics or underlined to keep your formatting consistent.

2.5 Consistent Terminology

You’ll have to include a section on consistent terminology to help writers understand how to refer to important parts of your SaaS and your organization. Using a glossary as an accompaniment to your style guide is helpful in this way, as in Document360, you can save important terms to your AI-assisted glossary so everyone is on the same page.

Section 3: Writing Style

3.1 Concise & Straightforward

As part of your documentation style guide, you’ll want to include a few words on how to write your content, which means letting writers know they should be concise and straightforward. This part of the style guide refers to the tone of voice you’ll use in your knowledge base. Avoid going off on rambling tangents in favor of direct explanations.

3.2 Active Voice

Ask your writers to use active rather than passive voice: this means saying things like “Click the button” rather than “The button should be clicked”. This makes your writing clearer and more dynamic, and helps users understand your content better.

3.3 Second Person (You/Your)

You should always instruct your writers to use the second person when writing your content, which means using “You/Your” rather than “Him/His” or similar. This is because you want to focus your documentation on the user and engage them more in your content.

3.4 Neutral & Professional Tone

Another aspect of tone is remaining neutral and professional. There’s a time and place for personality and humor, but knowledge base users want to get right to the answer. All technical writers must know this and adhere to a professional standard.

Get Started with Document360

Section 4: Visual & Media Usage

4.1 Screenshots & GIFs

Let your writers know how to use screenshots and GIFs to visually illustrate your help documentation. This could include the appropriate way to annotate your screenshots, where and when they should typically be used, and how to save your images for easy reference.

4.2 Alt Text for Images

To make your knowledge base more accessible, include how writers should use alt text with images. This means providing an alternative text-based description for every image you use in your knowledge base, which helps in case an image doesn’t load or if readers are using assistive technologies.

4.3 Callout Boxes

Callout boxes contain supportive text that is separate from the main body. It should be considered separately from the main text, so let writers know when it will be appropriate to use this method of conveying information, while at the same time avoiding overuse.

Section 5: SEO & Readability

5.1 Keyword Optimization

When writing documentation for your knowledge base, you can’t ignore the importance of SEO. Instruct your writers to use keyword optimization to ensure your content can be easily indexed by search engines, so that it shows up in the search results when users search for help with a particular problem. Ask your writers to use the right keywords throughout your content to fully optimize.

5.2 Descriptive Titles & URLs

Search engines prefer descriptive titles and URLs, so make sure you ask writers to use proper descriptions in the title and URL. This means not leaving your URL as a string of numbers, containing a clear description of what your article is about, with words separated by dashes. In Document360, you can automatically generate search-friendly titles to use in your articles.

5.3 Internal Linking

Show how your content relates to each other by ensuring writers include internal links to relevant pages of the knowledge base. Internal links send signals to search engines that your site is full of helpful content. Internal links should be structured like any other link: a clear keyword phrase with a link to the page containing that topic.

Section 6: Accessibility & Localization

6.1 Simple Language

Similarly to writing style, you want to instruct your writers to use simple language in all documentation aimed at your end users. This means using straightforward terms when possible, such as “use” rather than “utilize,” and using the most obvious names for each component of your product.

6.2 Translation-Friendly

To potentially localize your content more effectively in different languages, write your content in such a way as to be translation-friendly. Whether you are using machines or professional translators to translate your content, avoid using idioms that are specific to your native language and use short sentences with as few clauses as possible.

6.3 Readability

Readability means that users of all education levels and technical prowess can easily understand your content. Let your writers know that readability is a top concern: tools like Hemingway can help you get your readability score as low as possible.

Section 7: AI and Automation in Style Guides

7.1 AI-Generated Summaries

Let your writers know you are using software such as Document360 to generate article summaries with AI. These summaries can give a concise explanation of your article without requiring users to read the entire text, saving time for your technical writers and your target audience.

7.2  Automating Tagging

AI can automatically generate tags for your documentation to give your users even more ways to search for helpful content relevant to their initial query. Instead of writers having to think of more tags themselves, they can simply ask Eddy for a related range of tags that perfectly link to the article in question.

7.3 Metadata and Search Optimization

Provide helpful guidance on metadata and search optimization. AI can automatically generate article metadata based on the body of your content to display in search engine results. Meta description is a concise description of your article topic that is friendly to search.

7.4 Using AI-powered Analytics to Measure Content Effectiveness

It’s not all about writing your content. The style guide for your knowledge base should show writers where they can find AI-powered analytics that will give insight into your content effectiveness, allowing you to refine documentation so it is even more helpful for users. Instead of continually creating more content, identify articles you can improve

Recap of Key Takeaways

When you’re creating a knowledge base style guide, there are many elements you need to include to provide the most comprehensive support to your technical writers. A knowledge base style guide is an internal document that contains instructions on how to write documentation intended for your own unique company knowledge base.

From the use of images to voice and tone, to considerations for search, you should talk about any area of your knowledge base that you want to standardize to ensure that knowledge base content is speaking with a consistent voice. Even the presentation of links can be the difference between a professional resource and a site that amateurs have thrown together.

And of course, your style guide itself can also be its knowledge base: in Document360, you can create an extra knowledge base to accompany your documentation that instructs your staff in how to write content. If you keep style guides and documentation together, technical writers are more likely to use the former.

Standardize your documentation process with a powerful knowledge base style guide. 

START NOW