Re: Documenting Floating windows - how would you do it?

Subject: Re: Documenting Floating windows - how would you do it?
From: "M. Dannenberg" <midannen -at- SI -dot- BOSCH -dot- DE>
Date: Fri, 23 May 1997 11:14:17 +0200

Carla Lotito wrote:

> The documentation is by module in the software and includes field
> descriptions. However, window X can be accessed from module A, B and C.
> Different users may use each module but it is possible that the same user
> use all modules. The documentation will be delivered as a whole, not by > module.

I've got one of those too, shall we call them spaghetti apps? Early on I
decided to strictly only document everything once. I try to follow the
logical structure of the application, so that a user who would use all
parts of the program would fnd that the order of manual chapters roughly
corresponds to the order in which they'd use the different parts. That
way, even if somebody jumps in from somewhere in between, there should
be a reasonable straight path from there on.

Apart from that I try to anticipate as many alternative paths as
possible and put in cross references for those. I always try to keep
cross references to a minimum, though, as too many of them just add
uneccessary noise (I've seen documents that consisted of about 25% cross
references to the point of complete unusability).

As most things in techwriting it's a case of "You're damned if you do
and you're damned if you don't". You're damned if you put in too many
cross references and the user ends up having to flip through pages
constantly. You're also damned if you keep repeating information and the
user frequently has to skip redundant material. Getting the balance
right is what makes techwriting difficult - and interesting.


Mike Dannenberg
midannen -at- si -dot- bosch -dot- de

TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send commands
Search the archives at or search and
browse the archives at

Previous by Author: Paper size and PDF for online docs
Next by Author: Re: ATM vs. TrueType
Previous by Thread: Re: Documenting Floating windows - how would you do it?
Next by Thread: Documenting Floating windows - how would you do it?

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

Sponsored Ads