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

[Yves JEAUROND <jingting -at- rogers -dot- com>]

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.
   
  Regards,
   
  YJ
  
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.
http://www.DocToHelp.com/TechwrlList

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

---
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 http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.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/ for more resources and info.