Re: Too many tables in documentation

[Tim Altom <taltom -at- IQUEST -dot- NET>]

At 12:22 PM 1/30/97 -0400, you wrote:
>Hello everyone
>
>My department has been struggling over the issue of using field and
>description plus procedural tables in our documentation.
>
>Here is our problem:
>
>We are documenting a payroll/hr software application which uses many
>windows, tabs and pages. Each window (or screen) has to be documented for
>paper and online help reasons (we use doc-to-help). To define what's on
>each screen, we first have a field and description table and then later in
>the section we have a procedural table (step/action) that guides the user
>through any action that has to be carried out for that screen. Since our
>documentation is somewhat screen driven, it is turning into all tables. We
>have looked through all types of different documentation related to our
>field, and no one seems to be running into this problem. (Their procedures,
>if any, are buried within paragraphs and field/description screens are also
>described in paragraph format.)
>
>Any feedback on how to solve this problem, or if you know the current
>trends for field/description plus procedural tables within user guides
>would be greatly appreciated
>

We've run into the tabular information logjam in ISO 9000 environments,
among others. If I understand your problem correctly, you're worried about
the prevalence of tables. Is this because it's spreading out over too much
screen space, limiting user understanding, or is it making the file too large?

We've attacked the table problem first by preplanning as much as we can,
then by picking an appropriate tool. First, we reduce steps to stepwise
lists and try to isolate them into paragraphs of their own, and topics of
their own in help files. Any field descriptions go into secondary
sections/topics that the user can turn to, but aren't immediately presented.

We also passed away from Word a long time ago for such work, preferring
Frame instead. Its table functions are much more sophisticated than Word's,
if we have to do tables at all. But given the undoubted need for many, many
cross-references in your case, I'd use a tool that makes those easy to do
and maintain.

Most important, however, is that we don't normally use tables for anything
but the starkest references. Troubleshooting goes into tables quite often,
for example. But decision trees don't, and simple procedures almost never.
Even software that's heavily screen-driven doesn't have to have screen
captures everywhere and procedure tables to interpet them. I know that some
authorities, like the Info Mapping folks, like procedure tables. For us, we
find them often distracting when simple stepwise instructions do just as
well. See Microsoft's own Windows 95 procedures for examples. Why, after
all, include screen captures when the application itself is readily
available just a window or two down? If you feel it necessary to include
screen captures, then perhaps you could have a context-sensitive link from
each screen/box to a stepwise procedure topic, with an optional link to a
topic with an SHG of the screen capture. This would have popups for the
elements.

You didn't say what platform you were developing for, but it strikes me if
you're developing for Windows 95 or NT that you'd be well advised to
incorporate What's This? help and eliminate most of the tables that way.

I'd recommend to you both William Horton's Designing and Writing Online
Documentation and Deaton/Zuback's Designing Windows 95 Help. Both are loaded
with alternatives to tables.

All of this, of course, betrays my antipathy to tables. They're easy to
create and they often convince reviewers that the subject has been
adequately covered, but they're not often all that useful for users,
especially if most information has been presented in them. Further, in
WinHelp you  can't enclose them in borders, which can make the user squint
too hard trying to hold the cells together in her mind.

Tim Altom
Vice President, Simply Written, Inc.
317.899.5882 (voice) 317.899.5987 (fax)
FrameMaker support  ForeHelp support
FrameMaker-to-HTML Conversions
HTML Help Consulting and Production

http://www.simplywritten.com/simply

 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