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.
Melonie Holliman <melonie -dot- holliman -at- TXEXMTA4 -dot- AMD -dot- COM>
asks about combining "explanation of screen", "how-tos" and
theoretical/historical information in a manual.
How you organize this information depends on how the program
itself is organized and used. If the program is not organized so that
most functional tasks cannot be accomplished from a single
screen/menu option (or simple series of screens), then you might
consider making most of your manual a "user guide" organized by
functional topic, with a small reference section (organized by
menu/screen, but only giving a brief explanation and pointing to the
appropriate functional sections). The theoretical/historical
information in this case would probably belong in the functional
section - but it depends on the information.
For my manuals, I am fortunate that similar and related functions
are usually grouped on a single menu or nested set of menus. If
the same screen is needed for different functional areas, it usually
appears on more than one menu. My manuals are primarily
organized as reference guides. At the start of each section
(corresponding to a menu), I provide an overview with functional and
theoretical information; if certain functions require using other
menus first or later, then this is included in the overview. I also
provide a brief overview at the start of each menu option (sub-
section) which is similar, but corresponds to the option level.
