Re: STYLE: Prefaces/Introductions

["Susan W. Gallagher" <sgallagher -at- STARBASECORP -dot- COM>]

Bev Parks wonders...

> This leads to several questions for general discussion:
> 1. Do *you* read front matter?

Yes, most of the time. More importantly, when I encounter
a typographical convention that I don't quite "get", I turn
to the front matter for clarification -- and I'm *very*
disappointed if clarification isn't there!

> 2. Do you agree with Ms. Thoma that most people *don't read*
>    prefaces or introductions?

No. And I don't think that including front matter should be
settled via any democratic process. One of the things that
we must try to accomplish is to accomodate as many different
learning styles as possible. Including front/introductory
matter does this.

I recently took an informal telephone survey of about 15
beta sites to ask them about the introductory matter in
the front of one of my manuals.
5 thought it superfluous and wanted it gone
5 didn't care
5 thought it the most important part of the book and
  would miss it if it were gone

> 2. Do you use a preface and/or introduction in your documents?
>    Why or why not?

I use a preface that includes an overview of the
information contained in the book (e.g. Chapter 1
contains installation instructions, etc.), typographical
conventions (e.g., courier bold = information to type
or information conveyed by the computer, as in messages),
and other conventions (such as mouse instructions).

I also include an introductory chapter that explains
what each section of the program does and offers
suggestions for use.

Additionally, I usually include an overview chapter that
explains each of the menu items, toolbar buttons, and other
main-window components. Often this is the chapter that I
read in other books -- and often it's all I need to read!

Sue Gallagher
StarBase Corp, Irvine CA
sgallagher -at- starbasecorp -dot- com