Geoff-Hart.com:
Editing, Writing, and Translation

Home Services Books Articles Resources Fiction Contact me Français

You are here: Articles --> 2004 --> Just the FAQs
Vous êtes ici : Essais --> 2004 --> Just the FAQs

Just the FAQs

by Geoff Hart

Previously published as: Hart, G.J. 2004. Just the FAQs. Intercom May:24–26.

One of the most potentially useful components of documentation is a set of answers to "frequently asked questions", commonly known as an FAQ. The goal of an FAQ is to gather together in one place the kind of information that people most commonly seek, and in so doing, help them solve their problems without having to assemble solutions from bits and pieces of information scattered throughout a manual. Yet FAQs are often badly designed, undermining their usability and potentially increasing calls to technical support when a frustrated reader gives up searching through the FAQ.

It's certainly possible to create an effective, usable FAQ if you pay attention to the details. (Let's assume for the sake of this article that you know how to write effective solutions.) When you design an FAQ, focus on the following points:

Create an effective structure

The most common problem with an FAQ is that the questions are listed in more or less the same order the designers wrote them. This may mean that answers to questions concerning a specific topic are scattered throughout the document, often widely separated. This kind of (dis)organization forces users to skim the entire document, examining each topic to determine whether it relates to their need. Moreover, it prevents serendipitous discoveries, such as when the reader solves a problem by combining the answers to two related questions that appear close together.

The end result is that many users, myself included, detect the lack of organization, lack the patience to continue browsing, and turn elsewhere for help. We'd never consider writing printed documentation or online help this way because we recognize how useful it is to gather related topics into their own sections. So why not do the same in the FAQ? Organizing the material in an FAQ into logical groups helps readers to quickly reach the collection of topics that interest them, and lets them browse the answers to related questions to see whether they might also apply to the current problem.

Because some topics might reasonably be grouped under two or more headings, make sure these topics can be found under each of these headings. If the FAQ will be printed, consider repeating the full text in each location. Referring readers to a distant page also works, but has the disadvantage of forcing readers to flip pages. Try to avoid doing that, because it takes readers out of their thought process and out of the current section. If you adopt this approach, note this repetition somewhere so that when it comes time to update the FAQ, you'll remember to update all instances of that text. If the FAQ will be provided online, create the answer as a separate topic that isn't physically stored under any one heading, and use hyperlinks to link to that answer. This has the additional advantage of not repeating the text, so you'll only have a single chunk of text to maintain.

Of course, if you take readers out of their current context (e.g., the section of the FAQ on printing) to reach information stored in a different section, provide an easy way to return to their starting point. Because it's easy to get lost if you rely on a Web browser's Back button for navigation and follow many links, consider opening the topic in its own secondary window. Closing that window immediately returns the browser to the starting point for their excursion without forcing them to remember how they got there. Many pundits criticize this approach because it can lead to a proliferation of windows on the desktop, but if you limit the approach to a single secondary window at a time, the usability improvement should compensate for the annoyance of spawning a second window.

Facilitate skimming

How do readers find the sections that interest them? The same way they'd do in a printed document. Start with a comprehensive table of contents that lists the sections, topics, and subtopics in the FAQ. A table of contents lets readers jump right to the most relevant section without having to pass through all the irrelevant material that precedes it. Just as no large user manual comes without a table of contents, no FAQ should be without one. This is particularly true if you expect the product being described in the FAQ to grow, thereby acquiring an increasingly long FAQ. Planning now for growth means that you'll have an easier time managing that growth.

Once readers reach the desired section of the FAQ, you must still facilitate skimming—but this time, the goal is to help them find the start of each question and answer. Skillful use of typography and white space can solve this problem, just as it does in a printed manual. Give each question a title that stands out from the background so that readers can scan right ahead to the headings without ever having to distinguish between the headings and the text they introduce.

If you're forced to issue your FAQ in ASCII ("text") format, as is still common with "read me" files and similar aids, formatting becomes more difficult. But judicious use of simple keyboard characters and blank lines can create an equally usable design. Figure 1 provides several examples of how you can do this.

Figure 1. A few alternatives for setting off headings in ASCII designs.

Character

Example

Notes


Underscore
( _ )

_____________
Topic 1 heading

_____________
Topic 2 heading


Note that the line of the underscores lies immediately above the heading for the topic, and is itself preceded by a blank line. This approach is effective because the merged characters closely resemble a line, and the white space above the line separates the line from the surrounding text.

     

Hyphen
( - )

---------------------
Topic 1 heading

---------------------
Topic 2 heading

Follow the same approach as with underscores. Note, however, that the spaces between hyphens make the line appear to have been drawn with a pen running dry. That can look unprofessional.

     

Pipe or bar
( | )

||||||||||||||||||||||||||||||||||||
Topic 1 heading

||||||||||||||||||||||||||||||||||||
Topic 2 heading

This character lies to the right of the brace brackets { } characters on most keyboards. Alternatives include forward and backward slashes ( / and  \ ), though the greater amount of white space between these characters may create a more visually prominent and thus more distracting pattern.

     

Combinations of characters

||||||||||||||||||||||||||||||||||||
Main heading
||||||||||||||||||||||||||||||||||||

Introductory text

_________________
Second-level heading

You can emulate the effect of typographic distinctions by combining these characters. Use the most visually prominent characters (here, the pipe) for main headings and increasingly less-prominent characters (here, the underline) for subheadings.

Whether formatted using boldface and different fonts, or "typeset" using keyboard characters in an ASCII file, it's clear that blank lines ("white space") effectively set off each question from the surrounding questions. This relies on the information design principle of grouping things that belong together (a single question and its answer) while separating these grouped items from things that belong apart (other question–answer pairs). In addition to helping readers find headings while skimming, this approach has the beneficial effect of opening up the design and making it look less dense—and thus, less intimidating to read.

Simplify the wording

Now that you've organized the information and made it easy to differentiate headings from content, pay close attention to the wording of the headings and content. Start by eliminating redundant wording; for example, if the current section is clearly about printing problems, don't include the words "printing problems" at the start of each line. Doing so forces readers to read then ignore these words as they come to each heading. Instead, choose words that focus on the task the reader faces (creating, deleting, saving, etc.).

Traditional FAQs present these headings as questions ("How do I create a printer configuration?), since the Q part of the acronym is, after all, "questions". Though there's nothing dramatically wrong with this approach, and it does have the benefit of making the FAQ seem more informal and friendly (as if you were asking the questions of someone), the repeated "How do I?" seems unnecessary, and definitely slows the act of skimming: rather than simply reading about the action or task, readers must read and mentally discard the "how do I" part for each heading. Why put them through all that work? The purpose of an FAQ, after all, is to answer questions, not ask them.

Given that technical communicators have almost universally abandoned heading styles based on questions in our documentation, and have replaced it with action headings ("Create a configuration", "Creating a configuration"), it's reasonable to ask why we don't do the same in an FAQ. The best answer I can offer is what I've already mentioned: that doing so makes the FAQ look too much like the rest of the documentation, potentially making it seem less friendly to readers who have sought the FAQ as an alternative to the documentation. I'm not aware of any usability studies that confirm whether this reasoning is correct.

Because an FAQ may be used by those who find the manual too intimidating or less convenient, keep the explanations simple and friendly. Where a more complex answer is required, or to provide additional support for those who want or need more details, provide clear cross-references to the part of the printed manual or online help that provides this information. This has the additional beneficial effect of encouraging readers to consult these resources, perhaps demystifying them and making readers more comfortable using the main documentation. Of course, if the cross-reference occurs in an online document, turn it into a hyperlink that takes the reader directly to the content they're seeking.

Provide search aids

Nothing is less effective than an unsearchable (or poorly searchable) group of randomly organized thoughts—the kind of design that forces readers to skim the entire collection of trivia, one section or topic at a time, in the desperate hope that they'll stumble across the one topic that interests them. An online FAQ should be searchable, whether through a dedicated (built-in) search engine such as is now common on many Web pages, or by ensuring that the browser tool (whether Internet Explorer or a proprietary text-display engine) can search the text. This can be difficult if your information is presented (for example) as a series of PDF files linked to a Web page, since PDF files aren't easily searched until you actually open the file in Acrobat Reader.

Consider providing an index instead of relying on a search engine. Search engines remain primitive and frustrating, in large part because they're incapable of understanding context. Moreover, it's not yet possible to tell them that (for example) you're searching for configuration information for your printer rather than configuration information for the network; although most search engines let you combine multiple keywords and exclude other keywords from your search, these functions are too complex for many users, and don't always work reliably even for skilled users.

Another problem is that few search engines permit the use of stemming or synonyms. Stemming is the process of identifying the root of a word (e.g., "print", in the words printing, printer, printout, etc.) so that users can search for all topics that contain that root. Although wildcards can sometimes be used (e.g., searching for "print*" finds printer, printing, etc.), this approach still misses many relevant topics; for example, searching for "find*" won't produce topics containing only found. A skilled indexer will add the most common synonyms that readers will attempt to find, such as searching for hard copy or output rather than just printing. Including index terms can also let the search engine find topics more effectively, since users have several different chances (one per synonym) to guess which word a topic contains. If the software you're using to present the information doesn't support a formal index, add keywords instead at the start of each topic so readers can search for these keywords.

Improve the software

All of these suggestions will certainly produce a more effective FAQ, but sometimes the obvious goal (improving the FAQ) doesn't reflect the real problem that needs to be solved. The real problem is often that the need to repeatedly answer the same question for a large proportion of your audience clearly indicates a design flaw in the product. An effective FAQ helps people solve their problems, but it's even more effective to eliminate the need to solve the problem in the first place. When you complete an FAQ, try to find time to discuss it with the product developers and propose some redesign work before the next release of the product. In this sense, the FAQ serves as an effective checklist of "things that must be improved in the next version", and using it solely as a device to answer questions misses a very real opportunity to improve the product.


©2004–2017 Geoffrey Hart. All rights reserved