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