Re: Anarchy in the USA!

Subject: Re: Anarchy in the USA!
From: "Michele Marques" <mmarques -at- cms400 -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 29 Oct 1999 11:44:15 -0400

Andrew Plato argued that standards and procedures have their
place as tools, like hammers and screwdrivers, but that making
someone follow standards and procedures will not make him
creative. He also argued that time spent obsessing over standards
and procedures is better spent acquiring information.

First of all, as an information addict, I completely agree with
Andrew about the value of information. Back when I thought I would
be a fiction writer, a writer leading a writing workshop advised us
students not to become English majors (especially in places
offering degrees in creative writing), but instead to study history,
politics, or other areas about the subject matter that concerned us.
I think the best thing I did for my technical writing was to not
realize early on that a career in computers could mean full-time
work as a writer - I studied programming, psychology and
linguistics and worked as computer operator, programmer,
helpdesk support, system administrator (briefly), trainer and
webmaster. My background helps me understand both the
programs and the users. I agree with Andrew that the knowledge I
take to the task of writing documentation is more important to
writing useful documents than my knowledge of comma usage and
whether all my documents use the same shape of bullet in bullet-

On the other hand, given that I will churn out useful information, it is
easier for the user to access this information when I apply
consistent styles across related documents, especially in
reference manuals. Most people are not trying to read references
manuals as they might read a novel. I have had to rewrite technical
writing that was written by an English professor who used typical
novel/essay techniques to keep his prose interesting, such as
varying the way similar concepts are expressed, instead of the
consistent approach of reference manuals.

I know that my reader is usually trying to get the information as
quickly as possible from the reference manual (or on-line help) and
get back to work as quickly as possible. By keeping a consistent
stylistic approach, he can quickly find the answer to his problem.

But the key is just focussing on consistency. I do not sit around
obsessing over styles. Once I make my decision as to how to
emphasize fields, where in the field definition to place field size
information, etc., I just keep using it. It doesn't really matter if field
size is at the start or end, whether field names are bold, underline,
or a different font family - as long as I keep using the same
approach throughout the manuals.

The only time I have ever focussed on procedures was when I was
assigned an assistant to do technical writing on a specific project,
but who had neither subject matter expertise nor technical writing
background/interests. By being explicit on every stage of
instructions, I was able to get a document that could easily be
edited - it had all the information I needed in the correct places. I
was able to finish that document in a few hours. For the next
document, I let her "just do it" (as Andrew might say). But she
didn't have the experience to "just do it" in an appropriate manner
and I spent almost as much time re-writing that document as I
would have spent just writing it from scratch.

Was I worried about stifling this person's creativity? No. She is very
creative, but I was looking for a usable document. When working
with someone with more subject-matter or writing experience, I
don't dictate procedure (although I will dictate or edit for style),
because I expect that an experienced person has already figured
out how to "just do it" and get useful results - or that I can specify
how the results differ from my expectations without having to
specify a procedure.

Of course, dictating a procedure did not result in an excellent
document from the inexperienced person, but it did result in an
adequate document that could easily be improved.

Michele Marques
Technical Writer, CMS Manufacturing Systems
mmarques -at- cms400 -dot- com
905-477-4499 x280

Previous by Author: Re: Converting 1000s of files to PDF
Next by Author: Re: Adobe Framemaker Training
Previous by Thread: Anarchy in the USA!
Next by Thread: FramaMaker Templates

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

Sponsored Ads