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.
The notion that a chapter is required reading and an appendix is optional is
a little too simplistic for me. The API reference in one of our manuals is
a chapter, but not everyone will need to read it. Same with the hardware
overview.
I prefer to think of chapters as containing fundamental information while
appendices offer supplemental or advanced information that is of interest to
a minority of the audience. Such material could disrupt the flow of the
document while adding little benefit for the task at hand in the majority of
cases (such wading through a troubleshooting section of a software
installation when the installation is proceeding normally). An appendix can
also act as a catch-all for a lot of little pieces of information that might
otherwise turn the flow of reading into stop-and-go traffic--stuff like
references and subroutines, or acronyms and definitions that were spelled
out at the front of the document but aren't otherwise handy for readers
jumping into the middle. After all, manuals aren't written like novels; we
should write manuals to allow users to reference specific information as
quickly as possible, then close the book and get on with other tasks.
Also, appendices tend to present information with very little adornment:
lists, tables, settings, code snippets, that sort of thing. They cater to
the users who know what they're looking for and have a grasp of the
situation already--explanation of fundamental methods and madness is left to
the body of the document and would be redundant to these users. I also
assume that the appendix user wants naked data, with just enough clothing to
give it a context. (Of course, I try to give it a simple yet attractive and
organized layout to make it easier to use.)
Geez, I'm waxing psychological. It must be Friday.
Cheers ... Kim
Kim Roper
Technical Writer, Product Integrity
Vitana Corporation
Ottawa, Ontario
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-based Help with Macromedia Dreamweaver! (STC Discount.)
**NEW DATE/LOCATION!** January 16-17, 2001, New York, NY. http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.
Sponsored by SOLUTIONS, Conferences and Seminars for Communicators
Publications Management Clinic, TECH*COMM 2001 Conference, and more http://www.SolutionsEvents.com or 800-448-4230
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
