Procedure How to Write a Manual!

[Reid Gray]

Thanks Andy, I agree.  
 
If words stick to your gray matter, echo in your head like music, and if you can't help yourself from teasing them apart at their roots and stems you are probably in the right profession.  To be a writer you need to love words.  
 
Also note "endianness" came originally from literature ("Gulliver's Travels).  
 
Agreed. Writers use words to suit the lexicon of their audience.  If you are writing for USA Today, it's best not to use the vocabulary of the Harvard Business Review.  If you are writing a release note or a README, you wouldn't want the tone and vocabulary to be more in line with a low-level language programmer's guide.
 
BTW: Great thread.
 
Reid
 

________________________________

From: framers-bounces at lists.frameusers.com on behalf of Andy Kass
Sent: Fri 5/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 rgray at interactivesupercomputing.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/rgray%40interactivesupercomputing.com

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