Re: Organizing OO Docs

Subject: Re: Organizing OO Docs
From: Victor Chapel <victor -at- TRCINC -dot- COM>
Date: Tue, 5 Nov 1996 10:11:37 -0400

Matt Danda <dandam -at- GATOR -dot- NET> writes:
> Does anyone have any information on how to manage
> object-oriented documentation projects?

I like "Managing Your Documentation Projects" by JoAnn Hackos
as a general guide. We deviate from most other types of
software projects by the volume of paperwork, most of which
we create before writing a single line of code.

A typical project includes most of these in roughly
the same order:
1. Propsal
2. Project Ground Rules/Charter
3. System Architecture
4. Integration Arcitecture, Technical Architecture, and
Business (or Information) Architecture
5. Proof-Of-Concept with minimal Documentation
6. Software Development Plan
7. Development Guides
Can include Guides to using Persistent Object Service,
Naming Service, Security, Event Handling, Error Handling...
8. We also provide our own reviews and recommendations of
vendor products such as CASE tools, GUI tools, and ORBs.

Some points that should be defined early in the process
because they can affect documentation:
1. Pick a design method and stick with it. We often start
with Jacobson Use Cases for preliminary design, then move
to Fusion, OMT, or Unified.
2. OO standards for request broker and services--OMG's CORBA
and COSS are the only options as far as we're concerned.
It wouldn't hurt to join OMG and get a complete set of
OMG's documents. They do an excellent job of describing
many complex OO concepts.

One thing you should NOT need to define early on, if ever, is
the _language_ for coding the objects. Following OMG's
standards should let you use any language, C++, Java, Smalltalk,
or Eiffel to code objects.

We also use Barbara Minto's "Pyramid Priciple" to help lay out
the document set and each documents internal structure. It
could be considered a hierarchical "object-oriented" method of
organizing information.

Documentation is crucial to OO projects because many different
programmer will usually be coding to the documented design.
If it's missing, wrong, or inconsistent you'll end up with a
bunch of useless objects.

Please write or call if you need more info,

Victor Chapel victorc -at- trcinc -dot- com 800-891-1459, x-3064
The Technical Resource Connection
a wholly owned subsidiary of Perot Systems Tampa
Implementing and Advancing Distributed Object Computing

Previous by Author: Re: Help with sentence structure
Next by Author: Male/Female thread
Previous by Thread: TechWriting on Internet
Next by Thread: Re: In house third-party manuals

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

Sponsored Ads

Sponsored Ads