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.
Raj wondered: <<Should all the fields in a screen be described in a
procedure. Or, should only the fields that the user types an entry
should be documented?>>
First off, you need to distinguish between a procedure and a reference
manual. In a procedure, you only document the required steps. In a
reference manual, you document everything, but usually without
reference to an overall procedure. As always when writing
documentation, we need to start out by thinking about why the reader
is consulting our docs (are they trying to accomplish an overall goal
or just learn the function of a specific field?), and use that
understanding to guide what we write and how we write it.
Most techwhirlers don't have time to write two completely different
documents (an entirely procedural doc and an entirely reference doc),
and explaining many procedures requires a combination both of the main
path through the procedure and of all the possible options. As a
result, we write hybrid documentation that serves both roles
simultaneously. That kind of documentation presents the overall
procedure clearly, while also providing easy access to a list of all
options that might conceivably be related to the steps of that
procedure.
How to accomplish this well? There isn't any good rule of thumb, since
every procedure and every series of dialogs is different. Often, field-
level information is best provided by a "what's this?" type of help,
which displays a brief description of fields and other interface
objects. (I'm sufficiently out of touch with modern help technology
that I can't provide details of how this works and its limitations.
Others can provide that information.) A better approach is to make the
individual fields and controls sufficiently self-explanatory that
there will be little need to consult the documentation; using
affordances (clues and instructions) to make this clear takes a bit of
work, but greatly reduces the need for separate reference information
in a help file and the amount of documentation required.
<<Also, if the user searches for information, should all the
information on that screen be documented, or only those headings that
are not self explanatory be described?>>
Depends, as always on what the reader is searching for. Your help
system must be set up so that readers can find both procedural and
reference information by using the appropriate keywords. Search tools
don't work well for this; indexes often work better, at least if
they're prepared by someone who understands indexing.
<<Can background processes be described in the procedure itself or as
notes?>>
As a general rule, you should only describe background procedures the
reader needs to know about to be able to complete their tasks and
reach their goal. For example, if you're documenting the Save
function, you don't need to explain how the operating system receives
this request from your software and works with the disk drive to
allocate space for the saved information. You do need to explain
whether it creates any temporary files that the reader will need to
dispose of manually (e.g., in all versions of Word before roughly Word
2003), whether it creates backup files and where to find them, and any
other aspects that might not be plainly visible, but that will
nonetheless be very important to the reader.
------------------------------------------------------------------------
Geoff Hart (www.geoff-hart.com)
ghart -at- videotron -dot- ca / geoffhart -at- mac -dot- com
------------------------------------------------------------------------
Effective Onscreen Editing: http://www.geoff-hart.com/books/eoe/onscreen-book.htm
------------------------------------------------------------------------
Free Software Documentation Project Web Cast: Covers developing Table of
Contents, Context IDs, and Index, as well as Doc-To-Help
2009 tips, tricks, and best practices. http://www.doctohelp.com/SuperPages/Webcasts/
Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
