Re: Beginning topic titles with "How to..."

Subject: Re: Beginning topic titles with "How to..."
From: Yves JEAUROND <jingting -at- rogers -dot- com>
To: Janice Gelb <Janice -dot- Gelb -at- Sun -dot- COM>
Date: Wed, 20 Feb 2008 10:32:28 -0500 (EST)

Absolutely: one should use a sub-heading for a procedure.
The more general question: is a procedure a topic?

To get back to the scope of a TOC, a "table" of contents
isn't meant to list all of the contents :-)
Does a technical reader need to be explicitely told
in a TOC that technical topics hold procedures?

In a nutshell: one should ask if the purpose of a TOC is
(a) index-like: to locate information in a book?
or (b) the author's advice on how best to approach the material?

In favour of (b)
Since the fifties, as Mortimer Adler pointed out in _How to Read a Book_,
the TOC of a great book shows a reader how to ideally sequence topics
--- in the author's opinion; where to start reading and what best comes next.
_The Chicago Manual of Style_ is a great example of this:
a very short TOC is offered; then mildly detailed sub-TOCs are given
at every section. This helps the reader see topics as needed;
not to drill down into the obvious materials that support each topic.
As for locating topics, a TOC is not an index.

In favour of (a)
In German, a TOC is called "Index". :-)
For short works, a detailed TOC can serve double-duty as an index.
We see much of this in works of the XVIIIth c. and the XIXth c. editorial
experiments where the structure of the work is repeated as much as possible
due to the paucity of facts, and to purportedly help novice readers.
Quite the opposite of today's minimalism, encapsulation and other information technologies.



Janice Gelb <Janice -dot- Gelb -at- Sun -dot- COM> a écrit :
Yves JEAUROND wrote:
> In a nutshell, isn't it all about:
> a topic ("x"+ing) and a sub-topic (To "x"/About "x"+ing)?
> One can use "To..." as a sub-head for a procedure, but
> numbered steps function just as well, to indicate a procedure.

Numbered steps do not appear in a table of contents, plus
a given topic might encompass several procedures or sets of
steps, so headings are useful to indicate the purpose of
each set of steps.

-- Janice

Janice Gelb | The only connection Sun has with
janice -dot- gelb -at- sun -dot- com | this message is the return address


Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more.

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity!

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

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 for more resources and info.

Re: Beginning topic titles with "How to...": From: Janice Gelb

Previous by Author: Re: Beginning topic titles with "How to..."
Next by Author: [off list] RE : Nested lists hierarchy and style
Previous by Thread: Re: Beginning topic titles with "How to..."
Next by Thread: Re: Beginning topic titles with "How to..."

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

Sponsored Ads