[Author Prev][Author Next][Thread Prev][Thread Next]
[Author Index (this month)][Thread Index (this month)][Top of Archive]

RE: Chapter summaries at start of doc: yes/no?

Subject: RE: Chapter summaries at start of doc: yes/no?
From: "Fred Ridder" <docudoc -at- hotmail -dot- com>
To: Sarah -dot- Bouchier -at- exony -dot- com, techwr-l -at- lists -dot- techwr-l -dot- com
Date: Tue, 24 Oct 2006 13:42:39 -0400

I use the same basic approach that Richard describes. It bothers me
a lot to have the first section heading immediately follow the chapter
heading without some sort of text. Before our last reorg, our pubs
group's templates called for one or more paragraphs to describe the
subject and scope of the chapter plus a hyperlinked list of the top-level
headings in the chapter. I've subsequently changed my mind about
the value of the chapter-level pseudo-TOC, but I have *not* changed
my mind about the value of the scope paragraph.

One thing I always try to do is use the full, branded name of the
product I'm documenting in that intro paragraph. This eliminates the
need to include the product name in the chapter title (which makes
the chapter titles longer and harder to parse and is basically a lot of
chaff when you generate the TOC). It also helps the reader confirm
whether they have the correct information in their hand if they have
printed out an individua chapter. And it gives the writer an easy way
to ensure compliance with the Legal Dept's mandate that a product's
name should appear with properly marked trademarks at its first use in
each chapter of a manual or other long document.

My opinions only; I don't speak for Intel.
Fred Ridder
Intel
Parsippany, NJ


From: "Combs, Richard" <richard -dot- combs -at- Polycom -dot- com>
To: "Sarah Bouchier" <Sarah -dot- Bouchier -at- exony -dot- com>, <techwr-l -at- lists -dot- techwr-l -dot- com>
Subject: RE: Chapter summaries at start of doc: yes/no?
Date: Tue, 24 Oct 2006 10:18:26 -0600

Sarah Bouchier wrote:

> 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
------

_________________________________________________________________
All-in-one security and maintenance for your PC. Get a free 90-day trial! http://clk.atdmt.com/MSN/go/msnnkwlo0050000002msn/direct/01/?href=http://www.windowsonecare.com/?sc_cid=msn_hotmail

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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:
RE: Chapter summaries at start of doc: yes/no?: From: Combs, Richard

Previous by Author: RE: Formatting entries in a FrameMaker List of Tables
Next by Author: RE: All about Dayton
Previous by Thread: RE: Chapter summaries at start of doc: yes/no?
Next by Thread: RE: Chapter summaries at start of doc: yes/no?

[Top of Archive] | [Author Index (this month)] | [Thread Index (this month)]

What this post helpful? Share it with friends and colleagues:

Sponsored Ads