Re: Organizing OO Docs

[Victor Chapel <victor -at- TRCINC -dot- COM>]

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        www.trcinc.com
a wholly owned subsidiary of Perot Systems        Tampa
Implementing and Advancing Distributed Object Computing