RE: More help needed

[Deborah Snavely <dsnavely -at- aurigin -dot- com>]

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.