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.
> In the last couple of companies I've worked for, the
> documentation template called for a summary, at the start of
> the document, of what was in each chapter. I'm contemplating
> getting rid of these, for the following reasons:
>
>
>
> 1. The Table of Contents should be sufficient to tell you
> what's in a chapter. If it's not succeeding, you need to
> reconsider your headings.
>
> 2. Ditto the index.
>
> 3. Nobody ever remembers to update the summary.
It sounds like the updates are the issue. Instead of changing the
template to get rid of the summaries, why not rethink their contents and
level of detail?
My template also calls for some introductory text immediately after the
chapter title and before the first Head1 pgf. But mine are usually quite
short and high-level, simply expanding on the chapter title. They rarely
need updating because the basic purpose of the chapter rarely changes.
Here are some examples:
"This introduction provides a brief overview of the ReadiVoice
Administration &
Maintenance Guide, describes the conventions used in this manual, and
explains how to get additional information or support."
"This chapter offers a general overview of the ReadiVoice conferencing
system
and its features, functionality, and components."
"This appendix describes the default voice prompts installed with the
ReadiVoice system, how they're used, and the ReadiVoice call flows."
Admittedly, others are as much as half a page (usually because of notes
and cautions). But in general, if more detailed background or
introductory material is needed, then "Overview" (or something like
that) becomes the first Head1.
That's one solution, anyway. YMMV. HTH!
Richard
------
Richard G. Combs
Senior Technical Writer
Polycom, Inc.
richardDOTcombs AT polycomDOTcom
303-223-5111
------
rgcombs AT gmailDOTcom
303-777-0436
------
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today! http://www.webworks.com/techwr-l
Easily create HTML or Microsoft Word content and convert to any popular Help file format or printed documentation. Learn more at http://www.DocToHelp.com/TechwrlList
---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
