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:"Wing, Michael J" <mjwing -at- INGR -dot- COM> Date:Tue, 13 Aug 1996 13:40:05 -0500
Shari;
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.
>Thanks,
>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-
