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.
Subject:Too many tables in documentation From:Steven Jong <SteveJong -at- AOL -dot- COM> Date:Tue, 4 Feb 1997 12:11:29 -0500
Heidi Margenau <Heidi_Margenau/USG -at- USGROUP -dot- COM> wrote to ask about the
problem of too many tables cluttering up her product manual. I had this
discussion just yesterday (and got to her January 30 posting today.
It seems to me that in trying to include both procedural information on how
to use a window or form and tables describing each field, you are mixing
together task-based and reference documentation. The problem with this
approach is that the two are best aimed at different audiences and
situations; combined, they get in each others' way.
To me, task-based documentation (think of it as a precursor to minimalist
documentation) tells you how to accomplish a task. That's all. Reference
documentation describes the characteristics of a product or product element.
The audience for task-based documentation is trying to accomplish something;
the audience for reference documentation is trying to discover or learn
something.
Given those definitions, trying to mix the two forms together simply makes
for a hodgepodge suitable for neither. I would suggest separating the two:
put your procedures together in the beginning of the document, and the
reference tables at the end. Better yet, put the tables online, as part of
help, perhaps with context-sensitive addressing (point to the field and click
to get a description). That way the document remains short, and the detailed
information is readily available.
Mixing the two together ignores task-based documentation, which came before
minimalist documentation. It's just such an Eighties approach! 8^)
-- Steve (trying to embrace the Nineties before it's too late)
=============================================================
Steven Jong, Documentation Group Leader ("Typo? What tpyo?")
Lightbridge, Inc, 281 Winter St., Waltham, MA 02154 USA
<jong -at- lightbridge -dot- com>, 617.672.4902 [voice], 617.890.2681 [FAX]
TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send commands
to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
Search the archives at http://www.documentation.com/ or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html
