Re: Concepts (was Technical Writing Tests)

[eric -dot- dunn -at- ca -dot- transport -dot- bombardier -dot- com]

<<concept docs are much more difficult to write. They demand intimate
and extensive knowledge of the content. And this factor, I believe, is the
overwhelming reason documentation lacks conceptual information.>>

While writer laziness or lack of detailed knowledge MAY be a contributing
factor, simple economics and time probably plays a much greater role. All
documentation is written on a budget and with deadlines. To write comprehensive
conceptual information about a product will require extensive time and budget.
And while both concepts and procedures are important, given a budget and/or
limited time which of the two can you provide in the best quality and quickest.
Also, which is the one that will be most complained about if it is missing by
the intended audience?
I'd hazard a guess that even if the audience is highly technical network
administrators implementing a security product that the most important section
to the vast majority of them will be the procedures not the concepts. Reasons:
- If the audience is truly technical, they probably know many of the concepts
already or they wouldn't have bought your product. If they don't know the
concepts your product uses or your product ignores the expectation of the users
with respect to a core set of concepts, your product is doomed to failure.
- While they may know some of the concepts, they don't necessarily have any clue
as to how your software implements the various functions and concepts that they
expect.
A product is purchased because of a need. The first thing a user is going to do
is think "I bought this to do a task. HOW do I do it." Later, they may explore
the concepts and learn the many other approaches and uses the product has. But
the initial need is HOW do I accomplish what I bought this for so that I can get
on with my job. If they can't figure out how in a short time the product will be
discarded.
To look at a less technical audience understand how writers use software.
Initially, when you sit in front of a word processor to write a deliverable do
you think "I'd like to learn the insides of this product and the concepts it
addresses/uses to produce documentation." or do you think "How do I open a new
document and bash out a procedure." First you'll be in the second group. Only
after a given time will you join the first group and start learning the
concepts. I think it's why people who love/understand Frame often hate Word and
those that love/understand Word often hate Frame. Because when they first sit
down they couldn't give a rat's a** what concepts either program uses. They want
to get their work done. To get their work done they need a threshold of concepts
to be treated exactly the way they expect and a good collection of How-To
instructions. Later, they'll learn the concepts of the specific program and
become proficient at developing their own processes and make the program perform
well beyond the How-To directives.
So I think must qualified technical writers with a impressive knowledge of the
technology will still be faced with first getting all the How-To directives
written as required by the tasks their audience will be required to perform
followed by what conceptual information remaining time and budget allows.

Eric L. Dunn



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
Buy or upgrade to RoboHelp X3 today and receive the WebHelp
Merge Module for FREE ($299 value). RoboHelp X3's all-new
features include conditional text, completely re-engineered
printed documentation output, Context-sensitive Help Toolkit,
single-source layouts, and more!
Order online today at http://www.ehelp.com/techwr-l


---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.raycomm.com/techwhirl/ for more resources and info.