Writing A User Manual (part 1) - Asking The Hard Questions (
Page 3 of 5 )
You should start thinking about the user manual right at the start, and
try to have the following questions answered by the time you actually
get down to writing it.
1. Who is the audience?
This helps you decide the tone and level of technicality of your
language, the depth in which the concepts need to be explained, and
(very important) the analogies that you can use (familiar ground is best
when trying to explain something new). Knowing the following parameters
about the intended users would help:
- What is their average age?
- Which computer software packages are they familiar with?
- What are the obstacles they usually experience while using these
software applications?
- What are the top five task(s) they plan to use your software for?
- What is their current level of expertise (novice/intermediate/expert)
in using particular software packages?
This information is useful when your software builds on existing
software currently in use. For example, if you are delivering an
intranet email utility that plugs in to Microsoft Outlook, it would make
sense to find out if your audience has ever used it, and to what level.
This also brings up an important decision: do you decide the minimum
technical expertise required of the users of your software, state it as
such in the user manual, and get on with things? Or, given the results
of your user profiling, do you take on the responsibility of bridging
the gap between the current and required level of expertise (maybe by
providing a short tutorial as a precursor to the manual)? The schedule
and budget would normally make this decision for you.
The ideal scenario, of course, would be that you get all this
information by interviewing the actual users. In case that isn't
possible, your marketing and QA departments should have the requisite
insight into the target audience.
Besides this, some research into the business processes of the target
organization will give you even greater insight into the context of user
tasks, as well as fodder for analogies that may be easily understood y
them. Additionally, customer meetings, including technical reviews, are
great sources of audience information.
2. What is the scope of the document?
While the broad goals of the user manual would be to provide information
on the installation, usage, administration and troubleshooting of the
product, questions like these would help scope the document further:
- Current user expertise versus required expertise: What is the extent
of background/explanation that needs to be given?
- Supported platforms: What are the different platforms/operating
systems that the manual should address?
- Troubleshooting: What level of troubleshooting are the users supposed
to handle? Is there a reporting mechanism for support? Is there separate
documentation for troubleshooting?
3. What tool should you use for document development?
The user manual, online help and searchable help essentially build on
the same information. Which means that your choice of tool, and its
ability to allow you to reuse information from one document for the
faster development of another, is crucial (especially if your project's
on a tight schedule).
A number of good tools are available for this purpose. I like RoboHelp
(
http://www.ehelp.com/), though if you're working with XML, you should
also look at the XMLMind XML Editor (
http://www.xmlmind.com/)
4. What is the mode of document delivery?
The user manual can have two modes of delivery and distribution:
- Print: In this case, you take the responsibility of printing it
in-house and delivering it to the customer (many customers demand this).
The
downside: you get to incur printing and distribution costs (and the
accompanying logistical issues), together with recurring costs every
time the documentation is revised.
- Electronic: In this case, you may choose to deliver documentation in
electronic format, via CD-ROM at installation time, or provide
downloadable material on your Web site. The de facto standard for such
electronic documents is Adobe's Portable Document Format (PDF).
Again, if you're not sure what the final format will be, and if you're
comfortable with XML, it's worthwhile considering developing your
document in XML; this may then be easily converted into any other format
at a subsequent stage.
