Re: Chapter summaries at start of doc: yes/no?
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.
However, if my logic were really that overwhelmingly obvious and
correct, nobody would be using start-of-document summaries. So... what
am I missing?
We include a brief list in the book preface of the
chapter titles and what each chapter includes. To
answer your points in order:
1. The Table of Contents doesn't serve the same purpose
as a list of chapter titles and brief descriptions. For
one thing, chapter titles are limited to 5 or 6 words,
which in many instances can't fully describe the contents
of the chapter. Also, chapter titles often include
terminology that makes sense only after you've learned
something about the product or interface.
2. To use an index, you have to know what you're looking
for. A chapter description list could potentially let
readers know about some content that they might not think
of or expect to be included in the book.
3. At the very least, the links to the chapter will
be correct as we already check for them automatically
but it's true that if content is added or deleted to
a chapter, the writer potentially could forget to
update the description.
My approach on this issue is that our summaries are at
most a page for a long book and as they potentially
help the reader and don't hurt anything, why not provide
them?
-- Janice
***********************************************************
Janice Gelb | The only connection Sun has with
janice -dot- gelb -at- sun -dot- com | this message is the return address.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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-
To unsubscribe send a blank email to techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com
To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com
Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.
References:
Chapter summaries at start of doc: yes/no?: From: Sarah Bouchier
Previous by Author:
Re: Open vs Appear, Yet Again (was: "RE: WG: Newbie question - GUI terminology")
Next by Author:
Re: FWD: What to do about a recommendation?
Previous by Thread:
Re: Chapter summaries at start of doc: yes/no?
Next by Thread:
Re: Chapter summaries at start of doc: yes/no?
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads