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.
Deborah Hemstreet wondered: <<When working on online Help, how would
YOU distinguish between the pure HOW TO (delete, add, use a dialog
box, etc.) vs Why would I ever want to do this to begin with.
Conceptual information that, without knowing this up front, you'll
never know you NEED to add, delete, etc.)>>
Start by understanding what readers need to know before they actually
begin reading the details. Think of these as "critical points of
failure": if they don't know this critical information, they will
fail. For example:
"Before you can do this procedure, you must have done the following
procedures or have the following materials available [list]"
"Before proceeding, make sure you have identified all the directories
you must include in this procedure and ensure that you have the
permissions you require to work on these directories."
"Ask all other people to leave the room before you begin this
procedure."
"Before continuing, confirm that your breathing equipment is working
correctly and confirm that you have at least 1 hour worth of oxygen (X
psi) in the tank."
That's the essential context you should provide. There may be
additional context that's useful, such as shortcuts, cross-references
to related topics, and so on. The question to ask is what the reader
needs to know. In procedural information, people already know why
they're using a product feature, but may not know how that feature
fits into the overall process of achieving a larger goal. In reference
information, they don't know what something does, let alone why they
might use it, so you need to provide even more context: what does this
feature actually do, and how does that fit in with my overall goal of
getting home by 6 PM?"
<<Do Tutorials provide the concept as well as the how to?>>
Yes. Tutorials must provide an overview of what you're going to learn
and how it fits into the overall picture. This is how people assemble
isolated bits of knowledge (e.g., a tutorial on a single procedure or
tool) into the ability to use a product (i.e., by combining a series
of procedures to accomplish a larger goal). The goal of a tutorial is
to show people how to accomplish some task (en route towards
completing a goal composed of two or more tasks); the goal of online
help is to provide the details once you already know the overall flow
of the work.
Where many tutorials fail is that they do an excellent job of
describing a procedure, but don't relate it to any other procedures --
thereby forcing the reader to look at the complete list of tutorials
and try to figure out how they fit together and in what sequence.
Often, that's not at all obvious.
------------------------------------------------------------------------
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-