RE: Concepts (was Technical Writing Tests)

Subject: RE: Concepts (was Technical Writing Tests)
From: John Posada <JPosada -at- book -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 14 Feb 2003 10:36:08 -0500

I have procedural material called a RUN book (my HOW documentation, about
300 pages) and I have design material called my DESIGN document (my WHY
documentation, about 800 pages).

If someone wants to know how to run a procedure, RUN book. If they want to
know why something was designed the way it is, DESIGN document. I have both,
I just don't mix them together and that way, the reader can pick how they
want to address the situation.

OTOH, it seems that everything anyone needs to know about this whole
discussion was covered in the old Miller beer commercial.

...tastes great...less filling...tastes great...less filling...tastes
great...less filling...tastes great...less filling

John Posada
Senior Technical Writer
jposada -at- book -dot- com
icq: 178047452
aim: jposada1

-----Original Message-----
From: Jan Henning [mailto:henning -at- r-l -dot- de]
Sent: Friday, February 14, 2003 10:21 AM
Subject: Re: Concepts (was Technical Writing Tests)

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

I think it is of little value to make generalizations about users or
writers (or indeed about many other things).

Many users in many situations benefit from conceptual knowledge because
it makes it much easier to understand concrete steps they have to

But this is not always true. For example, I doubt that a burger flipper
needs much in the way of underlying concepts for his or her work - the
procedural steps of how to assemble the ingredients into a meal (using
the term loosely :-) is all they need.

So, once again, it comes down to knowing your audience and giving them
what they need. Frequently, that will mean at least some conceptual
framework, but not always.

Jan Henning


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: Try selling the sizzle of what you do.
Next by Author: Why they don't ask for candidates by technology skills.
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