TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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
tool.)
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.)
Thanks,
Eileen Neumann
Business Rules and Procedures
__________________________________________________
Do You Yahoo!?
Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com
WEBWORKS FINALDRAFT - EDIT AND REVIEW, REDEFINED
Accelerate the document lifecycle with full online discussions and unique feedback-management capabilities. Unlimited, efficient reviews for Word
and FrameMaker authors. Live, online demo: http://www.webworks.com/techwr-l
---
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 http://www.techwr-l.com/techwhirl/ for more resources and info.
