More help needed (documenting data records)?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Sharon Deitch wonders <<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). [or] Numbered steps that
take the user through the data screen, including all of the above
information.>>

Consider it from the viewpoint of the user, not abstract theory or personal
preference: will your readers primarily be trying to look up one or two
fields to refresh their memory or figure out something that isn't clear from
the data screen, or will they be reading linearly through the entire list of
fields while they're learning about the data record? Pick a solution that
meets their specific needs. The former audience requires a lookup table,
since their primary goal is finding something fast. The latter audience is
more willing to read through a pile of information, since they're looking
for an overview and understanding of the whole context; thus, they'd benefit
from a structured presentation of information that facilitates acquiring
this understanding. That doesn't mean a numbered list would be most
appropriate, since numbered lists work better for performing tasks than for
learning.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca

"Technical writing... requires understanding the audience, understanding
what activities the user wants to accomplish, and translating the often
idiosyncratic and unplanned design into something that appears to make
sense."--Donald Norman, The Invisible Computer