Revised questions RE: SDLC Documentation Help Requested

[Ed Manley <EManley -at- Solutionsplus -dot- com>]

Thanks, Margaret, that was very thoughtful to include the templates! And
thanks to everyone else who answered with suggestions, ideas and stories.

This verifies what I had supposed, that I am using pretty-much
industry-standard docs.

The templates a couple of you shared with me are almost identical in
purpose, content, form and structure to the docs I use and have used for
many years. 

The list of documents you use is pretty much the standard for software
development, particularly in the waterfall methodologies. The basic outline
of these doc templates (in slightly different form) appears in the RUP and
on the SEI website if anyone needs them.

My problem wasn't very clearly stated, I don't guess. 

My questions have more to do with process or workflow; I suppose, though,
that I did ask what documents you are using.

Now that we know our starting point, the templates, how are you
creating/maintaining the documents? 

Here's a for instance:
A Client uses our Enhancement Request template to create a request for a new
report to be added to the system.

Client Admin uses our Business Requirements template to elicit and document
initial (functional) requirements for the report.

Our CCB (Change Control Board) decides that yes we indeed will do this
enhancement, and assigns me (a BA) the task of creating a Functional
Specification, Solutions Approach and Work Estimate (all of which I have
templates for).

The client signs off on the deal, and I am assigned the project.

I create a Requirements Specification if the project is of any size, or just
a Technical Specification, which is created regardless of project size.

Our CCB keeps us posted on any Change Requests that come in.

I work closely with the coders throughout the development effort, and then
with the testers throughout QA.

I edit the User Guide to describe this enhancement.


So far, so good. The documentation is current, accurate, usable,
maintainable.

Now, multiply that scenario by thirty, which is the approximate number of
enhancements I am working on at any given time.

Mix in six more BAs, all working on numerous enhancements. 

(We maintain Domestic, International and one Custom version of our software
and may have four releases installed at various client sites at any given
time, may be working on multiple release candidates of any one of those
variations concurrently, and we have versions for Oracle, Sybase, DB2, etc.
We may have as many as seven hundred issues in our Issue Tracker that are
being worked simultaneously)

Throw in two new Tech Writers (Well.....one and a quarter).

Add fifteen developers and ten testers, each working on whatever part of the
chaos they can get a grip on.

Now - who is maintaining the Functional Spec for my poor little report
enhancement? How are they even gonna find it?

And, next year when I am retired (wore slap out) and the developer has quit
in disgust, whose gonna know how to maintain/enhance that itty biddy report?

And, since that report can be called from five different screens, how are we
gonna keep all those GUI documents current when the report changes? How we
even gonna know, when we go to change one of those screens (Visual Basic
forms) somewhere down the road, that it even affects my poor baby of a
report?

Say I wanna add a new function entirely. I want to add a manual data entry
screen that allows users to enter a description of their cat.
I want that description saved in the database. I want to add these feline
descriptions to my precious report.

How am I gonna know all the stored procedures and classes and VB modules and
tables and forms and so on that my enhancement is gonna touch?

How can I update - and here's the important part - How can I update ALL the
documentation that is affected by my enhancement?

Lastly, pretend I am stupid enough to come out of retirement and go back to
work. How do I know what the current system is? How do I find the details of
that cat report thingy we wrote a while back?

In our current environment there are so many people editing so many
documents for so many different reasons that you cannot trust a single
document. 

These are the things I am trying to solve!

Have fun,
Your thoughts are surely appreciated,
Ed

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Collect Royalties, Not Rejection Letters! Tell us your rejection story when you 
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of 
your book. What are you waiting for? http://www.iuniverse.com/media/techwr

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.

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