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.
Subject:WinHelp structure comes first? From:Tim Altom <taltom -at- IQUEST -dot- NET> Date:Fri, 5 Jan 1996 14:53:00 EST
Here's a question for those whirlers doing WinHelp projects.
Simply Written's policy is to advise WinHelp-writing clients to create a
structure first before writing topics. That way there's a road map, an
architectural plan that lets us catch structural mistakes before adding the
complexity of content.
This means that it's necessary to put the entire (at least 90%) structure on
paper before even firing up a software tool. It's a bit tedious and it goes
against the grain of writers who, after all, want to write, not plan. But
we've caught a lot of errors on paper, which was a lot cheaper than finding
them in the system.
I have, however, been in discussions with the other camp, the "accretion"
school of WinHelp creation. In that methodology you would create only a few
large-scale topics and then create topics within them as you come across the
information in the source materials. In effect, the file would grow as the
information tank fills, the same way a reef grows.
I object to this chiefly because it gives no control over the structure. The
project can't be adequately planned or managed that way, since you have
absolutely no idea how large the file will be, nor how complex. Project
planning and management is, of course, of vital importance to us as a
contract house. But I'd think that internal staffs would do well to adopt
the architectural approach, if only to satisfy management's inevitable
demands for time estimates. I've had people suggest to me that this method
worked well when the software being documented was completely developed by
accretion, too. But my response to that is that you'd do well to run like
hell from any software grown rather than designed.
I understand why the accretion approach is so attractive. First, it gives
maximum freedom and flexibility, paying for them with the maximum chance of
failure. (I define "failure" as "coming in after deadline and/or over
budget.") Second, it lets a writer immediately start doing what she wants to
do. Third, it can make management happier if they're the kind of folks who
value activity over meticulous planning.
I'm open to other arguments, though, and I'd be interested to know if
anybody has reconciled these two views. In my mind, there are infinite gray
zones between them, because an architectural approach is never 100%. But I
try to push it as high as I can. Anybody got a good case or anecdote for
doing an accretion WinHelp project?