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.



From: on behalf of Andy Kass
Sent: Fri 5/22/2009 4:25 PM
To: framers at
Subject: RE: Procedure How to Write a Manual!

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

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 

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 


akass at

> Date: Wed, 20 May 2009 14:51:39 -0400
> From: "Reid Gray" <rgray at>
> 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 " 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

Send list messages to framers at

To unsubscribe send a blank email to
framers-unsubscribe at
or visit

Send administrative questions to listadmin at Visit for more resources and info.

Reply via email to