TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: Conventions pages (WAS: Pros and Cons....) From:"Diane Brennan (Write Stuff)" <a-dianeb -at- MICROSOFT -dot- COM> Date:Thu, 28 May 1998 16:37:41 -0700
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.