Procedure How to Write a Manual!

[Richard Melanson]

I also have enjoyed reading the thread I started and appreciate
everyone's input, it has helped me to keep a "clear head" regarding this
issue. 
Rick
PS: I am an Electrical Engineer who worked in Engineering, then in a
Product Support and Field Service position before becoming a Technical
Writer, so I guess I have been on both sides of this fence.  

-----Original Message-----
From: framers-bounces at lists.frameusers.com
[mailto:framers-bounces at lists.frameusers.com] On Behalf Of Andy Kass
Sent: Friday, May 22, 2009 4:25 PM
To: framers at lists.frameusers.com
Subject: RE: Procedure How to Write a Manual!

I've enjoyed reading all the input on this thread, and I had a few more
thoughts.

Unfortunately, the way Reid writes it below, it looks like anyone can
have the writer role. I would've written:

4. Technical Writer who knows enough to understand the SME, learns about
the audience and its lingo, distills all the essentials out of these to
make an easy to absorb document, and knows the tools and formats well
enough to do it all quickly.

In any job, I think people need their core skills but also an
understanding and certain competency in the skills of those around them.
To that extent, I'm sure engineers can and do write decent docs
sometimes, but they're probably more efficient at their engineering
tasks.

I'm pretty sure we all know this, but it is exactly this that is
important to communicate in the case of this pointy-haired boss. Nor
does the boss seem to understand how a good writer can save money and
improve customer satisfaction. To be a good writer, you also have to
understand where management is coming from...

BTW, I actually don't think it's productive for writers to use big words
for the sake of using big words. Writers must use whatever words speak
to their audience.

  Andy

akass at jaspersoft.com

> Date: Wed, 20 May 2009 14:51:39 -0400
> From: "Reid Gray" <rgray at interactivesupercomputing.com>
> Subject: RE: Procedure How to Write a Manual!
> 
> I think the list agrees that not just anybody can write a good manual.

> And "No," writers cannot be just "anybody."
> They must be committed, they need to love language, and as Annie 
> Dillard says "...you really need to like words...
> words such as 'transmogrify'"  
> 
> Or, if you will extend the metaphor to IT, "endianess."
> 
> The best writing happens as a collective effort with the writer at the

> center. So, for example, take manuals. To write a good manual, one 
> needs:
> 1. Subject matter experts for authoritative content 2. Enthusiastic 
> reviewers who know the audience and have  exposure to the subject 
> matter 3. Editors who know the language 4. The technical writer
> 
> Trying as a single individual to serve in roles 1 through
> 4 is possible, but the more 'eyes' you have scanning the pages the 
> better the expected outcome.  This is especially true if you are 
> writing complete books, manuals, and periodicals, from scratch.
> 
> There is also an equally beneficial flip side to this postulate.
> If you find either "transmogrify" or "endianess" to be ugly, and if 
> you think anybody in particular can plant a garden, repair an 
> automobile, or write a technical manual, you might be management 
> material.
_______________________________________________


You are currently subscribed to Framers as rmelanson at spirecorp.com.

Send list messages to framers at lists.frameusers.com.

To unsubscribe send a blank email to
framers-unsubscribe at lists.frameusers.com
or visit
http://lists.frameusers.com/mailman/options/framers/rmelanson%40spirecor
p.com

Send administrative questions to listadmin at frameusers.com. Visit
http://www.frameusers.com/ for more resources and info.