Re: FAQs - Good or bad?

[Emily Berk <emily -at- armadillosoft -dot- com>]

Hmm.  I guess my perspective is skewed because I nearly always document APIs which are essentially useless unless they are relatively well documented.

In cases where the docs are good enough so that tech support can find most of the necessary information in them, the need for an FAQ is less compelling than in cases where the docs are not good enough.  (And, tech support should also have a database of information about previously resolved end user questions which would not be available to end users.)

One of the problems with FAQs is that they provide relatively short answers to clearly targeted questions.  An FAQ is probably not going to provide full context for answers to questions that require long answers.  And finding answers to vague questions may be difficult in even the best FAQs.

The fundamental problem with an FAQ (for me as a tech writer) is that it becomes just one more document that one must remember to update when the facts change.  And, it also becomes a half-hidden repository of incomplete information that users may be using.  

And then there is also the difficulty of finding an SME who "owns" the mish-mash that an FAQ.  Because the entire FAQ usually has no SME owner, updating the FAQ and getting it reviewed and QAed on a reasonable time schedule often becomes an issue.

That's one reason why I try to maintain my FAQs in XML that is imported into FrameMaker.  Associated with each question in the FAQ and each answer, I have an origination field which helps me to remember how/why particular issues got into the FAQ and which SME owned that issue.

I will (again) observe that (in my experience) if the docs are good (enough), then providing an FAQ becomes much less important.  And conversely, the less necessary the FAQ, the better the docs.

-- Emily

On Wed, 18 May 2005 11:56:18 -0700, "Gene Kim-Eng" <techwr -at- genek -dot- com> wrote:

>The type of client and the quality of the primary product documents
>are almost (but not quite) irrelevant.  Even if your company produces
>the best product docs in the world, there will always be a certain
>percentage of users who are just stubborn SOBs who prefer to pick
>up a phone rather than take the shrink wrap off the books or click 
>on a fileand RTFM.  

...

>Either way, providing users and your call center staff with targeted 
>lists of the most-asked questions so they can find them without 
>necessarily having to follow the entire workflow or even know the 
>context has the potential to help make life easier and reduce your 
>costs.
>
>Gene Kim-Eng

>----- Original Message ----- 
>From: "Emily Berk" <emily -at- armadillosoft -dot- com>
>
>> It turns out that I've written FAQs for two kinds of clients:

Emily Berk
http://www.armadillosoft.com



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

New from Quadralay Corporation: WebWorks ePublisher Pro!
Completely XML-based online publishing. Easily create 14 online formats, including 6 Help systems, in a streamlined project-based workflow. Word version ships in June, FrameMaker version ships in July. Sign up for a live, online demo! http://www.webworks.com/techwr-l

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.