Concepts (was Technical Writing Tests)

Subject: Concepts (was Technical Writing Tests)
From: Andrew Plato <gilliankitty -at- yahoo -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 14 Feb 2003 07:05:08 -0800 (PST)

"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. Likewise, all employers should require their
technical writers to be well-versed in the technologies 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.

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

> You should hear what they say about yours!

I am not going to respond to that remark.

Andrew Plato

Do you Yahoo!?
Yahoo! Shopping - Send Flowers for Valentine's Day


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: Re: Concepts (was Technical Writing Tests)
Previous by Thread: Re: Basic Voice ??s: OK for Software to "allow", "let", "enable",------ "pr ovide" and so forth?
Next by Thread: Re: Concepts (was Technical Writing Tests)

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

Sponsored Ads