RE: techwr-l digest: August 01, 2005 - cert comment and over-sized doc

Subject: RE: techwr-l digest: August 01, 2005 - cert comment and over-sized doc
From: "Nuckols, Kenneth M" <Kenneth -dot- Nuckols -at- mybrighthouse -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 2 Aug 2005 10:32:50 -0400

imac (Mike) mused...

> >
> >Of course, that's the point. EVERY job where the person writes
> >something benefits from clear writing...can you think of any job that
> >benefits from muddy writing (OK, government and legal are excused
> >:-)) we don't have a lock on that skill. I'm trying to figure out
> >what is at OUR core...that points to us.
> A quick note, here -- concise and clear are culturally-bound. Not all
> cultures value concise documentation, and concise is not always the
> tool in your toolbox. I say this because "technical writing" often
> includes writing non-technical documentation, as well; and actually, I
> see user guides benefitting from many examples that an otherwise
> and austere style would leave out.
> ~Mike

Just a quibble, and a minor one, but a quibble nonetheless. I would
argue that _User Guides_ (packaged with and accompanying the
product/software/system etc.) are best when concise, clear, and devoid
of excessive examples. When I open a piece of hardware or software I go
straight for the "Quick Install/Setup" guide and dive in head first.
The only time I go to the complete User Manual is when I need to
troubleshoot something, and that's mainly what I want it to tell me.

The type of documentation Mike describes is, IMO, better suited to
after-market supplemental documentation. I'm thinking of titles like
"Adobe <Product Name Here> Classroom in a Book" and the various QUE,
SYBEX, and other titles that are published for users that want to know
how to make a certain piece of hardware or software tap dance and
whistle Dixie backwards while simultaneously working out the orbit of
Neptune to the accuracy of a thousand decimal places.

I agree with Mike that TWs should be the ones to write these exhaustive
documents because many times they are the only ones who will have talked
to enough of the developers working on a project to get an idea of how
many different ways an end user is imagined to poke, prod, test, tweak,
fiddle, hunt, pry, search, use, abuse, misuse, and creatively wrangle
the final product. Even then, I'm sure some end user will bamboozle
everyone by doing something like use MS Project keep a grocery list, for

CONFIDENTIALITY NOTICE: This e-mail may contain information that is privileged, confidential or otherwise protected from disclosure. If you are not the intended recipient of this e-mail, please notify the sender immediately by return e-mail, purge it and do not disseminate or copy it.


Now Shipping -- WebWorks ePublisher Pro for Word! Easily create online
Help. And online anything else. Redesigned interface with a new
project-based workflow. Try it today!

You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit for more resources and info.

Previous by Author: RE: What do you call this doc?
Next by Author: RE: References (was: Why discuss certification?)
Previous by Thread: The future of tech comm: podcasting?
Next by Thread: What is the deal with Commvault?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads