Managing a FAQ

Issue

Technology companies consistently present information to new users in a quick-hitting Frequently Asked Questions (FAQs) format. In this format questions that are repeatedly encountered by support and field engineering are presented in an order usually grouped by major topics. Short answers are presented after each question. The format allows a user to quickly browse a large set of information for items of interest.

The issue is how to effectively use the Knowledge Center and KnowledgeDex to capture and present the valuable information collected by support and field engineers. This article is intended to jump start your ability to implement and manage a FAQ in SQI's Knowledge Center.

Solution

This and other referenced Help pages contain the directions for using the markup language needed to format and structure the text of the FAQ and general advice and instructions needed to implement and manage an FAQ. Using this resource, anyone with a limited understanding of the Knowledge Center should be able to be a successful contributor. It is strongly suggested that initially the FAQ be implemented with a small number of entries until the overall structure is established and checked. Once that is done, adding the major content can be accomplished quickly.

Expectations

If you are an experienced Knowledge Base user the process described below to set up the infrastructure for FAQs should take less than 10 minutes. If you are new to the Knowledge Base concept, the process, including reading and maybe some trial, should take no longer than 45 to 60 minutes. If you are new, the help pages for the Knowledge Base will provide a useful resource, and we recommend taking a few minutes to study them.

Once a FAQ structure is set up, adding a new question/answer and publishing will take only a few minutes.

General Considerations

FAQs generally consist of two types of responses, in-line (i.e. the answer text immediately follows the question) and downloadable (a link to a longer answer follows the question). Normally, short answers are written in-line longer answers are downloadable. It is advisable for the downloadable file to be attached to the page to facilitate updates and edits. Pointing to files that exist outside the Knowledge Base causes problems for remote users. When a FAQ is first established, it is often drawn from a variety of existing resources which might be in different formats or opened by different applications. Using downloadable files facilitates quick results and helps control the size of the FAQ, simplifying searching.

There is a blurry line between data that belongs in an FAQ and more voluminous data that belongs in a series of 'How Tos'. It is worth a little time to consider where, for you, the dividing line is drawn. Since it is easy to include downloadable files in an FAQ, there is no right answer. SQI recommends that in the beginning you lean toward including rather than excluding Q&As in the FAQ. This makes the task of finding relevant information easier for the user. As the number of long items increases, the difference between 'How Tos' and FAQs becomes more discernible.

FAQs often contain technical information including snippets of code. These snippets may interfere with the operation of the Knowledge base so they must be contained in a benign package.

Markup Framework

The FAQs for sophisticated products tend to grow rapidly as client questions raise issues that need to be documented. The collaborative, real-time publishing of Knowledge Base makes this process efficient. However, in crafting the FAQs we need to make sure that individual web pages do not grow in size to where download times and user navigation are negatively effected. Grouping FAQs into Sections, each with a specific focus, is the perfect structure to address this issue.

Figure 1: FAQ Sections

The model FAQ structure consists of a Master page that contains a Table of Contents showing the individual questions for each Section. After initial setup this page is automatically maintained by the system.

Each Section page contains an automatically generated Table of Contents (ToC) at the top, followed by each individual question and answer

The following links will take you to the markup, or specific instructions for the given function. The result will be a three level FAQ containing:

• A top page with a set of links to subpages
• An automatically generated table of contents
• A set of subpages with a series of questions and answers each with their own ToC.
• Question and Answer components that are automatically numbered and indexed for search
• The ability to attach a file to a page for downloading

Creating the FAQ Master Page

This link provides instructions and the necessary markup for establishing the master or top level entry page

>>> Creating the FAQ Master Page

Creating Sections

This link provides the necessary markup code for establishing Section pages.

>>> Creating Section Pages

Formatting Text

This link provides guidance on formatting text

>>> Formatting In-line Text

Adding files

This link provides instructions for adding files to a page.

>>> Adding Files

Adding Questions and Answers

This link leads to instructions on adding questions and answers

>>> Questions & Answers

Code Containment

This link discusses how to protect code snippets from possibly interfering with the operation of the FAQ.

>>> Containing Code Snippets