RE: conceptual material in procedures

Subject: RE: conceptual material in procedures
From: "Kathleen" <keamac -at- cox -dot- net>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Thu, 21 Apr 2005 07:37:13 -0700

I've encountered lots of similar situations in documenting hardware and
its software. What I've done depends on the situation: how much
conceptual material is necessary at a point.

For example, in using some dialog boxes to set up a measurement, you
would have to click on the Set button before closing the box, otherwise
the settings wouldn't be saved. So I'd add a small paragraph/sentence
saying that (maybe with an Important tag) before going to the next step.

That's a really simple example. For more complex material, you can state
what must be done (or set up a straw man) and direct people to an
explanation/section/chapter somewhere else, with a note that it's
important to understand the different options. There are several
approaches to doing this, and thinking about it, I recall some instances
when there was a lengthy paragraph or two inserted, with a reference to
a later section with more in-depth material.

It can be tricky, and I usually found it took several rewrites to be
moderately satisfied with the approach. But I also found it fun to do
when I felt it was working. One thing I found to be really important was
a tight document structure--using chapter-section numbers, and lots of
subheaders. This chunked the material so that it was easy to refer to
and (hopefully) easy for the "user" to understand and work with.

If you like I could send you a pdf of one of the more complex setups. It
wouldn't be understandable, but I could point out a couple of examples.

Hope you have fun


Eileen Neumann wrote:

I'm writing a user guide for employees of a financial company. The guide
explains how to perform a particular transaction. There are two aspects
- the how to, i.e., how to use the database, and a large conceptual
component. This is knowledge that you don't necessarily need to perform
this task, but that explains why you do some actions. An example is why
you choose code T as opposed to code C. I can give a table that explains
what code to put in what situation. But there is also a lot of
information on why the code is correct, and how the system is making
decisions in the background.

I want to include this kind of conceptual information. However, I know
that for procedures, you usually tell how, and don't burden the reader
with why.

Has anyone run into this, and if so, how did you handle it? (A separate
manual is not an option-management wants one manual.)


Eileen Neumann
Business Rules and Procedures


Accelerate the document lifecycle with full online discussions and unique feedback-management capabilities. Unlimited, efficient reviews for Word
and FrameMaker authors. Live, online demo:

You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit for more resources and info.

conceptual material in procedures: From: Neumann, Eileen

Previous by Author: RE: [HATT] ARTICLE: Choosing an XML Editor (
Next by Author: RE: conceptual material in procedures
Previous by Thread: RE: conceptual material in procedures
Next by Thread: Re: conceptual material in procedures

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

Sponsored Ads