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.
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:
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
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