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.
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
--
Mike Dannenberg
ETAS GmbH & Co.KG
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
to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
Search the archives at http://www.documentation.com/ or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html
