Re: Concepts (was Technical Writing Tests)

Subject: Re: Concepts (was Technical Writing Tests)
From: "Bonnie Granat" <bgranat -at- editors-writers -dot- info>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 14 Feb 2003 07:30:57 -0800 (PST)

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

> "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
> they document.


> 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
> 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
> 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
> procedures. The
> bureaucrat types that just want instruction with no
> context can flip past the
> conceptual stuff. The people that like to know why,
> 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


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

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 for more resources and info.

Previous by Author: Re: Technical Writing Tests
Next by Author: Ethics, ownership of product, and suchlike
Previous by Thread: Re: Concepts (was Technical Writing Tests)
Next by Thread: RE: Concepts (was Technical Writing Tests)

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

Sponsored Ads

Sponsored Ads