System Architecture / Documentation

[Megan Golding <mgolding -at- secureworks -dot- net>]

I'm working on an internal documentation project and am contacting
Techwr-l to gather ideas and opinions.

The project is an internal one, meaning employees of my company will be
the users. Our documentation will be used by QA to write test plans, by
the users to figure out how the heck this thing works, and by future
developers to figure out how the heck this thing works on a detailed
level.

Here is what we have in mind:
1. javadoc for the methods and classes -- written by the devlopers
2. task-oriented docs for the features (as defined by the requirements)
-- written mainly by me, the sole tech writer
3. short high-level architecture overview -- written by the lead
developer/architect

Task-oriented docs will focus on the requirements so we can be sure we
cover everything QA will want to test (and, as a byproduct, we'll have
the user docs covered).

I picture the final docs as being composed of:
1. various javadoc files output as html and accessed mainly by QA for
white-box testing. Some of these may be referenced by item #3, below.
2. an introduction to the "big picture" of this project and a few
diagrams explaining how the components fit together (this will be fairly
short, though).
3. a requirement-by-requirement description of how to accomplish that
requirement.

>From various readings and past experience, it feels like we're moving in
a non-traditional direction. I haven't seen many task-oriented internal
docs. Don't get me wrong -- I really like this approach. I'm wondering,
though, if we're going to miss out on some big piece of the puzzle that
needs documenting.

For techwr-l, my questions are these:

1. When writing internal documentation, what pieces are required to make
the project documentation complete?

2. Are we losing something by focusing our attention on documenting how
to accomplish the reqirements and not writing the grand architecture
doc?

Looking forward to your responses,
Meg

-- 

Megan Golding (mgolding -at- secureworks -dot- net)
SecureWorks, Inc.

Don't worry about the world coming to an end today. 
It's already tomorrow in Australia.
  -- Charles M. Schulz



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Announcing new options for IPCC 01, October 24-27 in Santa Fe,
New Mexico: attend the entire event or select a single day.  
For details and online registration, visit http://ieeepcs.org/2001

  Your monthly sponsorship message here reaches more than
  5000 technical writers, providing 2,500,000+ monthly impressions.
  Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.