TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Placement of question and answer sections in a user guide?
Subject:Placement of question and answer sections in a user guide? From:"Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Wed, 20 Mar 2002 13:29:09 -0500
Douglas Bailey is <<...creating a software user guide, and am planning to
include a list of commonly asked questions, though not necessarily as an
official FAQ. Do you think it would make sense to include it at the front
of the document, immediately after the (quite small) installation section?
Or is the more traditional method (to include it at the back, perhaps as an
Appendix) better?>>
In a larger sense, it doesn't really matter where you put such things, so
long as everyone can find it easily. If the section is listed in both the
TOC and the index, you could put it on any random page and they'll still
find it. But:
<<I'm trying to help the user avoid having to think... when a user decides
he needs help with something, he generally has a question he wants
answered.>>
The overwhelming problem with any kind of FAQ is that it's inevitably
presented out of context and out of order; that forces users to skim through
it until they find the specific question they're seeking--if they find it at
all. If you really don't want the users to go through this painful task,
forget about the FAQ entirely, and answer the questions directly in the
documentation. If the user has a question about (say) the Print dialog box,
they turn to the index, look up the page for "Print dialog box", and
voila--they've found the question and answer.
More to the point, anything that becomes a frequently asked question sends a
strong message that your documentation isn't doing its job. Rather than
setting up an FAQ section, make sure that the main body of your
documentation answers each question you were going to put in the FAQ section
quickly and easily. That turns the FAQ into a "seldom asked question".
--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
FERIC, 580 boul. St-Jean
Pointe-Claire, Quebec
H9R 3J9
"Writing, in a way, is listening to the others' language and reading with
the others' eyes."--Trinh T. Minh-Ha, Woman native other
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
PC Magazine gives RoboHelp Office 2002 five stars - a perfect score!
"The ultimate developer's tool for designing help systems. A product
no professional help designer should be without." Check out RoboHelp at http://www.ehelp.com/techwr
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
