Building a User Guide from FAQs

By July 18, 2016 Uncategorized

I’ve been asked a number of times now to convert a set of FAQ articles that live in a knowledge base, into a full‑blown user guide. Since this has become a recurring request from many clients, I thought I’d share a few tips on how to approach the creation of a formal user guide from an existing collection of articles, which are often disparate in nature and originate from different authors.

In practice, it’s actually quite common for organizations to start with a pool of FAQ’s before they have formal user manuals. This is often the case with start ups and groups which expand organically, especially where user support takes precedence in order to prove out the product’s robustness, and there is no time and/or budget available yet for formal documentation.  However, when such organizations reach the point where more formal copy is required, the knowledge base tends to be the only archive of information available to create documentation from.

The best approach is to allocate a technical writer who can take ownership of the project, identify gaps in information, and tie things together. While this can be assigned to an in-house person, it can also easily be outsourced to a contractor as well, since the bulk of the information exists. Having a dedicated person who can focus on documentation will ensure that technical and support operations can continue while the documentation is being assembled. A dedicated resource can also act as a go‑between person, seeking information from various subject matter experts, thus facilitating contributions towards the formal documentation from everyone.

Before diving into the pool of FAQs, first decide what type of user manual you want to create. Some manuals start with reference material and list step‑by‑step instructions later on, while others mix the two. Knowing what type of manual you want is important, because it will help you with the next step, which is to catalogue and organize your FAQ’s.

When it comes to content, FAQs tend to be very disparate. Each article tends to focus on a very specific workflow or provides information on a very specific problem. Therefore you should start by organizing common workflow related articles together to form sets of step‑by‑step instructions, followed by reference materials. You can then combine or keep these items separate based on how you want your user manual laid out.

As part of this process, be sure to identify articles which focus on listing things (e.g. specifications). This could include product bulletins or support articles which focus on listing features or specifications for certain product versions. Such articles are prime candidates for appendix material, which can be placed at the back of the user guide and then cross referenced from other chapters.

Once everything is categorized, it’s time to start building out a table of contents (TOC). Regardless of the layout of the user manual you are creating, the TOC is an important element for organizing the content and helping the user find what they’re looking for. Note that the development of the TOC may require several iterations, and the effort may span the duration of your documentation project as new information is added.

As the layout and organization starts to take shape, the next step will be to identify gaps in information. With FAQ articles typically being quite disparate and focused on different topics, you will likely have to modify and rewrite many of the articles that you’ve grouped together – both to tie together language and technical content. As part of this process, you will also likely have to work closely with subject matter experts who can add additional details, verify information, or even provide you with whole workflows which may not have been captured in the FAQs.

One caveat to avoid here is the temptation to leave articles in the same form as you found them in the knowledgebase. Doing so basically results in FAQ articles living in two locations (i.e. the knowledge base and your new manual). FAQ articles are often “reactive” in nature in the sense that they describe a solution to an existing problem, or detail a workflow that the user already knows at least something about. So, strive to break away from the FAQ language and format, and instead think of the content from the perspective of a new user learning the product for the first time. After all, you’re they’re instructor and your manual is their course material.

Once this has been accomplished, the final step is to tie everything together with good overview information for each section. This should explain what the reader will learn in a given section, why the information is important, and where they can find additional related information.

So, follow these steps the next time you have the task of creating a formal user manual from existing FAQs, and you should have the basis for a quality manual that you can continue to build on for years to come.