Menu Close

How to Build SaaS Knowledge Bases & Help Centers

How To Do Technical Documentation

We’re spilling the beans. This is how you do SaaS support centers. Our detailed outline below is applicable to any SaaS platform, web-based support center, knowledge base, help center, training program, or similar collection of informational articles that will be presented to end users for support – technical or otherwise. Some elements of these processes are not applicable to static documents like PDFs, but most are.

It’s not comprehensive, as volumes could be written on each line item. A lot of the magic is in the application to your specific requirements. Once your help center is built, using it effectively is also crucial.

Our list of 53+ tips should get you started down the road to customer service excellence. Contact us if you have any additional questions on building out your help content, or leave a comment below. It’s our specialty, and we truly enjoy doing what we do here at Doakio.

1. Support Center Architecture

To start your SaaS knowledge base, draft a high-level architecture for the information you need to document. Follow these steps below to progress through towards a good structure:

  1. Think about the high-level groupings in a way that would make sense from a customer’s perspective (and not necessarily what makes sense from an internal operations standpoint).
  2. If you have a very small number of articles you expect to write (under 20), then you should only have two levels of categorization. To use Zendesk’s wording: Sections > Articles.
  3. If you have more than 20 articles, then use three levels of categorization. For instance: Category > Section > Articles. Never use four levels of organizational depth unless you are a truly massive enterprise.
  4. Always aim to have exactly three categories. It’s okay to have four to six categories if the volume and content variance dictates. If you find yourself considering seven or more categories, try to combine two similar or smaller categories into one.
  5. Always aim to have exactly three sections in each category. It’s okay to have four to seven categories if the volume and content variance dictates. If you find yourself considering more sections, try to combine smaller or similar sections into one.
  6. Always aim to have roughly five to ten articles in each Section. If you have more, consider breaking it into separate sections if possible. If you have fewer, consider combining it with another section.

2. Prioritize Important Help Articles

Prioritize which articles should exist in your SaaS knowledge base before the drafting phase begins. You don’t want to write articles that don’t matter to your users. So following these steps will help focus on what matters most:

  1. If customer feedback exists (e.g. support ticketing system), analyze it for common pain points.
  2. Run a customer survey to determine what the most important parts of their support journey are, or what problems they’ve had.
  3. Survey internal support team members to find out what the most common customer problems are.
  4. Ask the management, developers or other stakeholders what they think are important factors to write articles for. It’s best to interview those who have front line experience with customers during this step, but if that isn’t available it’s okay to go into non-customer facing roles.
  5. Become a customer yourself and imagine being in their shoes. Take detailed notes on your first pass to identify areas of friction that you can write support articles on.

3. Be Consistent with Help Center Design

Consistency – Establish internal documentation standards specific to your company or at the very least, specific to the knowledge base. Your brand’s colors and overall identity should be consistent when moving from the platform to the help center.

  1. This is more important for larger technical documentation teams, where many people will be drafting and editing articles; and less important for smaller, one-man support centers. But even that one technical writer may not be on-staff forever, so it’s important for that person to describe the standards they used to ensure a smooth help center experience for the end user.
  2. Refer to these standards often, but keep in mind your own internal standards will vary based on where the content will be hosted and other factors.
  3. Include references to your company branding standards and style guides. Developing these are outside the scope of this document.
  4. Consider what the ideal image resolutions and dimensions are.
  5. Consider which tools and methods you will use to add highlight or callouts to the image.
  6. What resolutions and dimensions will you use to capture video? This may not be the same as images. The 16:9 aspect ratio is only important to adhere to if you expect the customer to view the video in full screen.
  7. Ensure the character set you use supports translation (UTF-8) if there is even the slightest chance that any of the support content may be translated into another language.

4. How to Draft Technical Support Articles

Draft your customer support articles for your support center. This is where the rubber meets the road.

  1. Adhere to your internal documentation standards, if there are any.
  2. Start from the very beginning. Try not to assume customers know how to get to every page on the platform just by referencing the page’s name. This is more important for complex user interfaces (with many options) and less important for simple interfaces with few options.
  3. If possible, go through the process yourself if possible to capture as much of the experience as you can. Take images or video during the process.
  4. After your first draft, refer to pain points from the research gathered in step 2. above to ensure they have been captured in your article.
  5. If the article is going to be publicly published, consider the SEO ramifications of the content. Optimize for SEO where possible.
  6. Keep the article as short as possible while still clearly explaining every step of the process. If you find the article is very large or lengthy, consider breaking it up into smaller articles. Try to keep it under 2,000 words.
  7. Scrub your content for word commonality:

    • Create a word list of every word used in your article
    • Use the Corpus of Contemporary American English (COCA), found at https://www.wordfrequency.info/.
    • Find your top 5 or 10 most uncommon words and consider replacing them with more common synonyms while maintaining readability and meaning.
    • Look for company-specific technical phrases that have different meanings than their constituent words imply. Ensure you clearly define these specific technical phrases separately the first time they are used in each article, or link to their definitions which you should add to your glossary.
    • Consider implementing a popup feature across your support center which shows definitions of uncommon terms when the user hovers over the word.

  8. Wait a full day, then re-read your article and follow your own instructions in the article to check for consistency.
  9. Ask someone else to proofread or edit it.
  10. Ask someone to take the steps explained in the article. This is not the same as proofreading.
  11. Avoid coming up with catchy titles for support document articles. Be brutally direct and accurate with your title and subject matter descriptions. This isn’t poetry.

5. Use Images in Support Content

Capture images for the support articles you write. It’s trite but true: “A picture is worth a thousand words.” At least, it can be true when the proper images are used.

  1. Use images often, but if you can capture multiple talking points in a single image, do so.
  2. Adhere to your internal documentation standards for images – be consistent with the colors and methods you use to add callouts and highlights to the images.
  3. Use a screen capture tool like Greenshot, Awesome Screenshot, JING (my personal favorite), or the dozens of others out there.
  4. If you ever expect to translate the content, make sure you never use text inside the image. Use numbers to specify areas in the image, then call out the numbering in the text before or after the image.
  5. Consider how frequently the user interface you are capturing will change. Whenever a major UI change comes out, you should recapture the images on the new interface to avoid confusion.
  6. If you are capturing images inside a web browser, ‘ZOOM IN’ so that the element you are capturing is large enough to see at the resolution in which it will be displayed to the reader.

6. Provide Full Tutorial Videos for Customer Support

Capture full support videos for the articles. Video is ever growing as the consumption method of choice for many users. Turn your support articles into full tutorial videos with audio voiceover.

  1. How to create a quality video tutorial is beyond the scope of this article.
  2. Embed the video at the top of the article.
  3. It’s easy to make a video from a support article, or make a support article from a video, by reading or transcribing respectively. Use this fact to ensure every support article you have has a corresponding full video. This will help with accessibility (e.g. for disabled persons) and it could help with SEO as well.
  4. If you are hosting on YouTube, ensure you turn off video suggestions at the end of the video using rel=0.
  5. Make sure your video has full captions in the hosted video-sharing platform to ensure maximum accessibility for disabled users and to give easier access to the search engines who can’t reliably decipher human speech quite yet.

7. Create Micro Videos that Auto Play & Auto Loop

Micro Video. Create micro-videos for your support content where appropriate to make it easier to understand intricate interactive steps.

  1. This will not work on mobile devices, so only use after tracking user behavior and ensuring that very few or no users access your help content via mobile devices.
  2. These are short, 2 to 20 second videos without audio.
  3. Record the video in such a way that it begins with the exact same frame as it starts on, so that everything flows smoothly when setting the video to loop
  4. These are best when a dynamic process needs to be shown, or they can be used to replace several screenshots
  5. Generally, you do want to zoom in on the action taking place, but it’s also important to capture enough of the screen so that the context and location where the action is taking place is perfectly clear including top menu items.
  6. Ideally, you want to upload the videos to the same server that is hosting the document (ideally) or some other public server space that is under the ownership control of the company who owns the document. Avoid a third party video hosting service such as YouTube, Vimeo, etc.
  7. Using HTML5, embed the video and strip out all control functions from the video. Set it to autoplay and auto loop indefinitely.

8. Ensure Open Customer Feedback on Support Content

Ensure open feedback channels on tech support articles to help with ongoing improvement and measuring support center success.

  1. At the very least, add your support e-mail address at the end of each article.
  2. Intercom and similar persistent help chat windows are usually great options.
  3. Consider adding a very simple article feedback form at the bottom of each article with an Email and Message field.
  4. You can also ask for more detailed feedback with questions such as:

    • Did this article help you? [Yes/No or 1-5 scale]
    • How was this article useful for you?
    • In what ways could we improve this article?
    • If you still need help, please describe the problem you are having…

  5. Respond to all article comments very quickly. Treat them like any other support ticket. Show your customers you are actively listening. Having an auto-responder is fine, but not if it refers them right back to the articles they are having problems with.
  6. Consider having social media contact options at the bottom of every support article if you monitor those accounts for support inquiries.

We’ve reached out to several expert writers, editors, customer support agents, and SaaS writers to get their additional feedback on these methods:


Tips on Writing Great Knowledge Base Articles

Professional Editors

Naina Professional Editor

Naina Said, Writer and Editor

“Great Article, Alexander! I’d like to add, with my experience as a professional fashion writer and editor, I’ve found that every article you write should have an introduction that is very clear. The first two lines should immediately and in clear words dictate what the users should expect in the rest of the article. Also, be sure to keep the sentence length short. If the sentences are too long, users can lose focus.”


Professional-Writer-Ruchi-Bhargava

Ruchi, Bhargava, Co-Founder & Managing Director, SparkinWords

“In addition to these tips, do remember most users love using a search feature. Consider your options there, and make sure it is capable of finding more than just exact matches, etc. While technical documentation images are often restricted by the content they are capturing, it doesn’t hurt to add an attractive hero image to the top of the article, especially when the article might be viewed by a wider audience than your existing customer base.”


Karla Maye Carreon, Experienced Blogger and Copywriter

“As you write technical documentation, remember to maintain a light, friendly tone so that the readers feel comfortable. This is a subtle way of improving on their support experience and sort of “build rapport.” Always be reminded that we are writing for the readers and not for ourselves, so we want to make it a point to not only inform, but to also mildly entertain.”


Professional Technical Writers

Tamara Wilhite, Engineer, Technical Writer, Six Sigma Green Belt

“Keep help desk staff engaged with tech support documentation. If you discover a new error message due to a software release or OS change, ensure that the issue and company approved solution is clearly communicated to tech writers to create a new solution. The sooner you have a formal solution for the matter, the sooner your customers will act appropriately in response to the issue – and if possible, solve it themselves. When the recommended procedure for dealing with a problem changes, ensure that it is communicated to the technical writers as well. Intense user experience studies are popular at the moment. What we often overlook is how often customers ask for features or give recommendations to the help desk. Create a process for capturing these recommendations and referring them to marketing, engineering or product development.”

So what are your thoughts? What problems have you run into when building out a help center? Did you find any of these steps useful? Let us know in the comments below!

Leave a Reply

Your email address will not be published. Required fields are marked *



By submitting this form, you are consenting to receive marketing emails from: Doakio, Brgy 2, San Francisco, 8501, https://doak.io. You can revoke your consent to receive emails at any time by using the SafeUnsubscribe® link, found at the bottom of every email. Emails are serviced by Constant Contact
https://doakio.com/technical-knowledge-base-process-outline/
doakio.com
crawl=CC-MAIN-2019-26
67052
application/http; msgtype=response
sha1:S7HNXUT57XORJPKRHMRGYGUKQRXGDEDA
<urn:uuid:5adffe2d-51dd-4f86-bd8d-284fdc39c307>
2019-06-27T06:30:29Z
78.142.0.81
text/html
sha1:E77GURTMRJSB4WTH3KB7UTKTNKMDNTKI
<urn:uuid:8b5febf5-995f-4569-9b78-a234b5ce5bbd>
https://doakio.com/technical-knowledge-base-process-outline/
response
<urn:uuid:6f94af17-9c74-4708-8982-179b1ef1dd3e>
isPartOf: CC-MAIN-2019-26
publisher: Common Crawl
description: Wide crawl of the web for June 2019
operator: Common Crawl Admin (info@commoncrawl.org)
hostname: ip-10-63-217-69.ec2.internal
software: Apache Nutch 1.15 (modified, https://github.com/commoncrawl/nutch/)
robots: checked via crawler-commons 1.1-SNAPSHOT (https://github.com/crawler-commons/crawler-commons)
format: WARC File Format 1.1
conformsTo: http://iipc.github.io/warc-specifications/specifications/warc-format/warc-1.1/