Was Pros and Cons of including writer's name; now conventions use d

Subject: Was Pros and Cons of including writer's name; now conventions use d
From: Toni Williams TPG/SG <towilliams -at- PROCYONGROUP -dot- COM>
Date: Thu, 28 May 1998 15:34:42 -0700

In response to the question "What's wrong with a Conventions Used
Section?"

Scott Miller responded:

>Waste of paper. Provides no useful information. The only useful
>convention-type info I've seen is how to read syntax stuff, like [stuff
>in brackets is optional], and also what language programming examples
>are written in. Otherwise, stuff like "key names are presented in
>all-caps bold" is self-evident.

It seems to me that to consider ANYTHING _self-evident_ is one of the
stickiest tar babies by which a tech writer can be caught. One of the
first rules I learned was that if something can be mis-understood it
will be. The tech writer's job, as I see it anyway, is to make something
as impossible to mis-understand as possible. Sorry, Scott, I have to
differ.

Respectfully,

Toni Clark Williams
The Procyon Group
Documentation Department




Previous by Author: Pros and Cons of including writer's name
Next by Author: Forget FTP and e-mail attachments for PCs
Previous by Thread: long: Coincidence? I think not. Release Notes and READMEs
Next by Thread: Novice question


What this post helpful? Share it with friends and colleagues:

Sponsored Ads


Sponsored Ads