Re: Concepts (was Technical Writing Tests)

["Bonnie Granat" <bgranat -at- editors-writers -dot- info>]

On Fri, 14 Feb 2003 07:24:41 -0800 (PST), Andrew Plato
wrote:

> 
> 
> "Bonnie Granat" wrote...
> 
> > Perhaps, if you don't know your subject and are
> struggling to explain a topic
> > that you don't fully understand. In that event, you
> shouldn't be making the
> > attempt. Conceptual information may be more valuable
> under certain limited
> > circumstances, but most users want to know how to
> *do* something.
> 
> If a writer does not know the subject, then they
> shouldn't be writing the
> documents in the first place. 

That's what I said.


Likewise, all employers
> should require their
> technical writers to be well-versed in the
technologies
> they document.
> 

Agreed.


> Furthermore, I firmly believe users want (and need) to
> know WHY they are doing
> things. When you accurately document the "why" and
> "what", the "how becomes
> almost incidental. If you understand why things work
> they way they do, then how
> to make them do that is relatively straight forward.

As Amy Smith pointed out, yes, in many instances users
*do* need to know the why and how of things. In other
cases, they don't. Perhaps there is too much variation
among users for one to make the blanket statements that
I made. Certainly Amy's examples illustrate that
conceptual information is mandatory to her users, while
it may not be for Excel or Word users.


 
> 
> > That assumes the software is well-designed and
> intuitive, and that users have
> > the luxury of spending five minutes reading about
> concepts.  A good procedure
> > introduces the steps in a process with just enough
> conceptual information to
> > prepare the user to perform the task.
> 
> I would argue that concepts are MORE important when
> there are design flaws,
> since you can't fall back on simplicity as a guiding
> factor.
> 
> Moreover, what is "just enough" conceptual
information?
> If I flip through most
> documents, "just enough" seems to be interpreted as
> "practically none." A
> paragraph here and there, with miles of procedures in
> between. 
> 
> > Maybe that's because most users of documentation
want
> to know how to use the
> > software, not how or why it does what it does.
> 
> Again, I disagree. Most users DO want to know why.
> Perhaps the absolute bottom
> of the barrel bureaucrat types only care for the raw
> procedures. But given the
> choice, users do want to understand the technologies.
> Moreover, neither item is
> mutually exclusive. Concepts don't have to intrude
upon
> procedures. The
> bureaucrat types that just want instruction with no
> context can flip past the
> conceptual stuff. The people that like to know why,
can
> read that. The
> inclusion of conceptual material does not degrade the
> document in any way (it
> of course makes it better.)

I would tend to agree with you about all of the above,
Andrew. Both are necessary. No documentation would be
adequate without one or the other.


> 
> > You should hear what they say about yours!
> 
> I am not going to respond to that remark. 
> 

You just did. 


Bonnie Granat
Granat Editorial Services
http://www.editors-writers.info

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
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.