FW: "Conventions Used in this Manual" wasRE: Emphasis

[Wohlrab Arleta - DRACS <wohlraba -at- BSCC -dot- BLS -dot- COM>]

 -----Original Message-----
From: Wohlrab Arleta - DRACS
Sent: Thursday, September 04, 1997 10:59 AM
To: TECHWR (everybody) (E-mail)
Subject: RE: "Conventions Used in this Manual" wasRE: Emphasis

(I'm resending this message because it was "undeliverable" the first
time--Arleta)

I agree that users should not have to go to a Conventions section to
decipher fonts, graphics, etc., but I think it's too much to assume that
no one needs such a section.

I always include an explanation of  conventions to help increase the
comfort level of the reader who likes to gain an overall framework of how
the book is structured. It doesn't take up more than a couple of pages,
and it doesn't take long to do. It may be a bit presumptuous to assume
that one's work is so   user-friendly that no one will need to verify the
meaning of a convention. This is especially true if your book will be
used by users who are not from the United States, as there are many
cultural factors to take into account.

However, if a book uses no graphics, the conventions section is not as
necessary.

Arleta
wohlraba -at- bscc -dot- bls -dot- com


 -----Original Message-----
From: Huber, Mike [SMTP:mrhuber -at- SOFTWARE -dot- ROCKWELL -dot- COM]
Sent: Wednesday, September 03, 1997 4:42 PM
To: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
Subject: "Conventions Used in this Manual" wasRE: Emphasis

I've been skipping the whole section.
I can't imagine anyone who isn't a writer bothering to read it, and our
guidelines don't require it.
If it isn't obvious just from looking at any random page in the book
(except for some specialized tables, charts, or graphics) you have a
problem that a bit of ignored "front of the book junk" isn't going to
solve.

There are some reference documents, like train schedules, that are meant
to be deciphered. But for a basic user's guide, the usual (at least in
the usability tests I've observed) sequence is that the reader flips to
the index (which better be the last thing in the book, or they won't
find it) and then skims the first or the most obvious paragraph on the
indexed page. End of story. No studying how to interpret the various
fonts - all our work either makes it obvious or fails in those few
seconds.

Obviously, there are other ways readers use manuals. But the fine points
are for our own use, to create an overall look that the reader will
never notice if it's right. Think about where you ate lunch - quick -
what material and pattern was the table-top? If it was clean and not too
garish and you aren't somehow a table geek, I bet you don't know. (No
fair referring to a photographic memory.) But it was an important part
of the dining experience. A dirty or garish table top would have been
poor form, which would have distracted you from the content of the meal.
Your readers probably feel the same way about what you apply emphasis
text styles to and what those styles are. If you get it right, the
information zings right past the eyes into the brain and the reader
forgets ever having not known the answer.

Mike Huber
mike -dot- huber -at- software -dot- rockwell -dot- com

>-----Original Message-----
>From:  Barb Philbrick [SMTP:caslonsvcs -at- IBM -dot- NET]
>...
>Out of curiousity (and a search for something better) - Do you call
>them "conventions"? My impression is that most people think of
>conventions as large gatherings of people. I've been trying to find a
>better title for the section where we describe these things. I've seen
>"Conventions Used in this Manual," and I'm currently using, "How Items
>are Shown in this Manual"...

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html