Re: Conventions pages (WAS: Pros and Cons....)

["Diane Brennan (Write Stuff)" <a-dianeb -at- MICROSOFT -dot- COM>]

A few months back, at my last company, I received a forwarded e-mail from a
high level manager, which was a very vitriolic complaint from a customer
that one of our documents (out of eight or so) didn't have a conventions
page.  The document was a change record (a list of new information to add to
the other documents) which went to existing customers, and it was the only
document that didn't have a list of conventions, but the customer was in a
foreign country, and conventions that we are accustomed to were not
self-evident to him, and it prevented him from completing a difficult task.
I should probably mention that the software was very complex and
non-intuitive, so that users were very dependent on the documentation to
help them through.

I want to add that a sweeping statement about conventions doesn't take into
account that there are different levels of documentation.  A highly
technical document, such as a programming guide, may rely heavily on
conventions to differentiate between functions, parameters, flags,
structures, methods, etc.

> ----------
> From:         Lisa Higgins[SMTP:lisarea -at- LUCENT -dot- COM]
> Reply To:     lisarea -at- LUCENT -dot- COM
> Sent:         Thursday, May 28, 1998 9:22 AM
> To:   TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
> Subject:      Re: Conventions pages (WAS: Pros and Cons....)
>
> The type of conventions pages I was talking about are the ones that I
> keep running across: output is in courier, input in bold courier,
> blah blah.
>
> I've had the opportunity to watch users using documentation, and I
> have never seen anyone look at this stuff. Besides, if users started
> wanting or needing this type of stuff, it would indicate to me that
> the document needed redesigning.
>
> > Also consider that what you think is obvious may not be obvious to a
> > reader in another country, a neophyte user, or a reader whose first
> > language is not English....
>
> I've worked with these guys. I had a perfect test group for a
> new-to-computers manual I wrote some time ago. They do read the docs
> much more carefully than experienced users do, but they STILL don't
> read the conventions section, in my experience.
>
> The reason for formatting input text, for example, in bold courier,
> is not to tell the users that this is input, but to draw the text out
> for people who are in a big hurry. The text itself should be very
> clear about why the text is there. Type <break> into the _computer_
> field, not <break> _computer_.
>
> If you're showing a screen shot, tell the user what the screen shot
> is in the main text.
>
> ~
>
>