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.
Lesli Ritchie asked, ".... Our software User Guides describe all the fields
on a screen and give the user step-by-step instructions on how to do
something, such as add a new record. I usually add a table that describes
the fields and their options in the context of the steps, but I feel that
this breaks the flow and could be confusing to a new user (our users have a
wide skill range). How do you handle this? Do you reference a table of field
descriptions within the instructions and then add it to an Appendix? Do you
keep it in the instructions? "
I include necessary screenshots in the process description, but not the
table describing the options. At the end of the procedure, I add a sentence
to introduce the table, like, "Table 2. Lists all the action buttons (or
field descriptions, etc.) that may appear (or be used) during the <name of>
process described above." The process description already includes the usual
option. The Table is provided for later reference if something unusual shows
up besides the usual, expected result.
Margaret Cekis, Johns Creek GA
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com