conceptual material in procedures

Subject: conceptual material in procedures
From: Tony Markos <ajmarkos -at- yahoo -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Sat, 23 Apr 2005 06:58:12 -0700 (PDT)


May I suggest that you consider the concept of
abstraction. Procedure can be expressed at both the
detail-level and at higher levels of abstraction.

User manuals are typically detail-level: they present
very concrete steps on how to exercise the system to
do specific tasks.

But, as in your current project, the reader may have
the need to step back and look at the "bigger picture"
to conceptually understand what the overall business
goals satisfied within the scope of system are - and
how specific tasks interrelate with each other (i.e.,
the "why we do something" as you say).

There are tools (especially modeling techniques) for
expressing procedure to higher levels of abstraction.
(Text is, by its nature, a low-level of abstraction

Sounds like you need straight-text to document the
detail-level procedure and a seperate tool for
documenting procedure to a higher-level of abstraction
(i.e., for documenting the conceptual stuff). (Note:
This bigger picture may be supplement, as required,
with text).

Tony Markos

Hello Whirlers,

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.

Because the material is for employees, and I'm talking
about their
jobs, 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

Do You Yahoo!?
Tired of spam? Yahoo! Mail has the best spam protection around


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.

Previous by Author: Definition of "User-Friendly" Was Re: Engineering design practice
Next by Author: Re: Definition of "User-Friendly" Was Re: Engineering design practice
Previous by Thread: RE: conceptual material in procedures
Next by Thread: Release Note Formats

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

Sponsored Ads