TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
It seems to me that your approach is to do a "parts of this" and "parts of
that"
Even though you state 'self-describing', 'self-explained', 'self-defined'
or similar phraseology in you document, you may have some who don't view it
that way.
You could organize your 'document' in two (or more parts).
Part I is whatever you want it to be. Covering forms, tables, etc., in
general.
And use the 'self-xxx' comment as you see fit. You can also refer the
'reader' to Part II which DOES have a complete description of the field.
For example, See Part II, (field xxx).
Part II contains a full description of each field. (Alphabetically, or some
semblance of similar order.)
This way you can address the form as a form, screen as a screen,
and explain what is needed to get the job done. And have a ready reference
that is comprehensive enough for your document audience to use.
Harry M. Bacheler, Jr.
Consultant
VGS, Inc.
"The thoughts, ideas, and opinions expressed in my portion of this email
are mine and mine alone. They are not the thoughts, ideas, and/or
opinions of any past, present, or future employers, or any group that I
might belong to."
-----Original Message-----
From: bounce-techwr-l-20951 -at- lists -dot- raycomm -dot- com
[mailto:bounce-techwr-l-20951 -at- lists -dot- raycomm -dot- com]On Behalf Of Stanley
Smith
Sent: Wednesday, 08 March, 2000 04:31 AM
To: TECHWR-L
Subject: Help describing fields.
Hi Techwr-lers,
I am working on a user guide for a complex software application being
developed for use by telecommunications companies.
The product has many different screens that they are calling Forms. Each
Form has a different function and has many different data input
fields that need to be described.
.. snip, snip ...
For consistency, what I suggest is to use a generic text to as the
desciption of these field types. Some have come up, but in my
opinion these > sound a bit condescending to the user.
(self-explained)
(self-defined)
Can you suggest a better way to handle this situation?
Any comments or suggestions would be greatly appreciated. Thanks
in advance.
