RE: Key Features vs. What's New

["Carnall, Jane" <Jane -dot- Carnall -at- compaq -dot- com>]

>Alison Tartt asked:
>In working on the sections "Key Features" and "What's New in This Version"
(both >sections in the Intro chapter), I'm having trouble avoiding a lot of
repetition >(same feature seems to belong both places). 
>Has anyone found a way to describe areas of functionality with a dual
>approach or emphasis so that they can go into these two different sections?

>>Thom Randolph responded:
>>The typical method I use is to create the Key Features
section, and include a cute little graphical marker
that proclaims "New in Version 7.3.0.4.2" or whatever.<<

The general system I use for any area of functionality which could or should
belong in two sections is to describe it thoroughly in *one* section: and
then create a link or a reference to the section where it is described. Use
an automatic cross-reference so that the page number remains up-to-date.
Never ever repeat descriptions of identical functionality: besides being
extra work, sooner or later someone will forget to update changes in both
places. 

However, in the specific instance that you describe, Thom's system of
indicating new features with cute little graphics in the "Key Features"
section sounds like as good solution, unless you need a complete list of new
features somewhere in the manual for contractual reasons. But I hope not. I
like cute little graphics.

Jane Carnall
Technical Writer, Compaq, UK
Unless stated otherwise, these opinions are mine, and mine alone.