RE: More help needed

Subject: RE: More help needed
From: Deborah Snavely <dsnavely -at- aurigin -dot- com>
To: 'TECHWR-L' <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 3 Oct 2000 09:35:10 -0700

Sharon Deitch asks:
>When documenting data records, which of the following would you find
>preferable:
>
>+ Listing all the fields in a table, including whether the field is
>required and what to fill in the field (also what type of data can be
input,
>where appropriate).
>
>+ Numbered steps that take the user through the data screen, including all
>of the above information.
>
>I prefer one method, and my boss the other. I'm purposely not saying which
>I prefer, so as not to skew the results. He's asked me to find out from
you
>good people which is considered the "acceptable" way.

You're both right. Depends on what the purpose of the document in question
IS.
* If you're writing a tutorial, a procedure, a training manual, then
the procedure is preferable (but only the minimum steps needed to
accomplish the procedure for the audience and purpose of your
document/document chunk). But this is the long-winded and boring
way to document all the fields in ANY database screen.
* If you're documenting the database format, or writing a reference
manual, or documenting screen by screen, or even under a government
or other contract that specifies that all commands, fields, screens,
etc.
must be documented, then the table is much cleaner. But not very
novice-friendly.
Usually, a database doc set needs both. A set of database tables can be an
appendix to a user guide, or may be core meat to a database administrator
guide. But a table in the middle of a procedure will cause the user to slow
down and have to puzzle the information needed out of that table.

Best of luck,
Deborah Snavely, Senior Technical Writer, Aurigin Systems, Inc.






Previous by Author: Re: New TECHWR-L Poll Question
Next by Author: RE: best application for taking screenshots (Windows)
Previous by Thread: Re: More help needed
Next by Thread: RE: More help needed


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


Sponsored Ads