Too many tables in documentation

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


Previous by Author: FYI - DENG XIOPENG
Next by Author: Resumes, cover letters, and home pages
Previous by Thread: Toilet Tricks and Other Babble
Next by Thread: Document Design Pub Announcement


What this post helpful? Share it with friends and colleagues:

Sponsored Ads


Sponsored Ads