Re: Documentation Architecture Question

Subject: Re: Documentation Architecture Question
From: "Wing, Michael J" <mjwing -at- INGR -dot- COM>
Date: Tue, 13 Aug 1996 13:40:05 -0500


Obviously I don't know the specifics of the software you are
documenting. Therefore, I'll shoot from the hip. Is it possible to
organize the software commands by functional families? For example,
file management, text editing, line draw, graphic importing/exporting,
and so forth. If so, maybe the documentation could be developed with
chapters that are containers for the functional families. These
chapters would link individual documents; one for each command.
Therefore, if a command is added or deleted, the impact to documentation
is minimized.

Let's say the development group is creating 2-d line draw commands.
They currently have the rectangle, arc, line, fill, circle; however,
they are not sure that the grouping command is going to work. The
container document could introduce 2-d line drawing and explain their
common functionalities (handles, line weight, bring-to-front, and so
forth). This document would then pull in the arc document, the line
document, and so forth. If the group command does make it, include the
group document. The command documents do not have to be stand alone,
they just have to blend into the container.

One of the keys to writing the container document is not address
specific commands (because the referenced command may be dropped).
Rather, address the concepts of the family grouping (such as using a
double click to terminate a multi-lined geometric shape - which could be
a polygon, bspline curve, and so forth). The specific commands, written
in separate documents, could then be linked into the document. If the
command is dropped, drop it from the documentation. If an entire family
group is dropped, drop the chapter.

Think of the container document as your grocery cart and the individual
command documents as your grocery items. The document is structured so
that commands can be added and replaced with relative ease without
damage to the containing document structure.

Mike Wing

_/ Michael Wing
_/ Principal Technical Writer
_/ Infrastructure Technical Information Development
_/ Intergraph Corporation
_/ Huntsville, Alabama
_/ (205) 730-7250
_/ mjwing -at- ingr -dot- com

>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?

>I'd appreciate any comments.
>Shari Scheske Goodman
>scheskes -at- cognos -dot- com

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-

Previous by Author: Re: A variation on the pencil test
Next by Author: Re: Online-only documents
Previous by Thread: Re: Documentation Architecture Question
Next by Thread: Help for a Newbie - response

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

Sponsored Ads

Sponsored Ads