Procedure How to Write a Manual!

[Andy Kass]

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.