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-boun...@lists.frameusers.com on behalf of Andy Kass
Sent: Fri 5/22/2009 4:25 PM
To: framers@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
ak...@jaspersoft.com
> Date: Wed, 20 May 2009 14:51:39 -0400
> From: "Reid Gray" <rg...@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 rg...@interactivesupercomputing.com.
Send list messages to fram...@lists.frameusers.com.
To unsubscribe send a blank email to
framers-unsubscr...@lists.frameusers.com
or visit
http://lists.frameusers.com/mailman/options/framers/rgray%40interactivesupercomputing.com
Send administrative questions to listad...@frameusers.com. Visit
http://www.frameusers.com/ for more resources and info.
_______________________________________________
You are currently subscribed to Framers as arch...@mail-archive.com.
Send list messages to fram...@lists.frameusers.com.
To unsubscribe send a blank email to
framers-unsubscr...@lists.frameusers.com
or visit
http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com
Send administrative questions to listad...@frameusers.com. Visit
http://www.frameusers.com/ for more resources and info.
