Re: Documentation Architecture Question

[Tim Altom <taltom -at- IQUEST -dot- NET>]

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.

Tim Altom
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.

http://www.simplywritten.com/simply

                  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-