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:Re: Documentation Architecture Question From:Tim Altom <taltom -at- IQUEST -dot- NET> Date:Tue, 13 Aug 1996 10:11:00 EST
At 10:46 AM 8/13/96 -0400, you wrote:
>Our software development team is building the software in increments.
>Once certain features are ready, they will be ready for shipping. This
>means the documentation has to be ready as well.
>The challenges we face are:
>* Due to the way the development team is building the product, we
>may have to document the software by feature. However, most
>documentation is provided based on use, not feature.
>* We may be almost finished documenting a feature, but the feature
>doesn't make it in the release because the development team is not
>finished. We then have to pull it out of the documentation.
>We are trying to figure out the best way to handle this. Any ideas
>lingering out there? Anyone else in the same situation?
This sounds like an organizational problem that's above and beyond your
level. Growing software like a reef is not necessarily the best way to run a
project, and it's murderous on the doc, because as you say the doc should be
task-based as a rule, while the project is essentially bolt-a-feature.
Is it possible to at least sit down with the project leader(s) and hammer
out a list of expected uses/tasks? They'd only be headings until the
features made them live, but at least you'd have an outline of your doc's
structure. Then you can fill it in later as the schedule permits. And you
can counter some of the helter-skelter with tighter PM of your own. Make an
assessment of how much you know, how much you don't, what can be done now,
and what can't. Then cast a quick forecast, complete with rough timeline.
This will nail down all the unknowns and let you plan intelligently.
As to the now-you-see-it-now-you-don't features, you can cut some of that by
using specialty software features in your DTP or WP package. FrameMaker has
conditional text, which is marvelous for doing things like that, while Word
can be made to serve somewhat in the same way by using include fields or
master document. But again, planning, planning, planning. You won't solve
any of your problems by succuming to the fire drill that's going on around
you. In that direction there be destruction.
Vice President, Simply Written, Inc.
317.899.5882 (voice) 317.899.5987 (fax)
FrameMaker support ForeHelp support
Makers of DuoFrame, giving you online help and paper
documentation from a single parent FrameMaker document.
TECHWR-L List Information
To send a message about technical communication to 2500+ list readers,
E-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send administrative commands
ALL other questions or problems concerning the list
should go to the listowner, Eric Ray, at ejray -at- ionet -dot- net -dot-