Re: Version control advice (long)

["Gary S. Callison" <huey -at- interaccess -dot- com>]

On Thu, 05 Jun 2003, a_whirler -at- hotmail -dot- com ("Writer Whirler") sez:
> Oh, you gurus of all things documentation..I seek your advice about how
> to control an uncontrollable document.

"One dragon at a time".

> I have been assigned the task of keeping current a requirements
> document for our corporate portal, a website from which hangs all
> sorts of applications, research, etc.

Hey, that's me too.

> Late last year, the company hired a consultant to take the 
> requirements, which had formerly been a whole bunch of separate
> documents, and combine them into one big document. It's nearly 300
> pages (a Word file)...

Ew. 

> The real dilemma for me is this:  Since I will be splitting up the doc
> into smaller pieces, how do I label them?

I'm dealing with the same thing. Here's how I'm attacking it:
There's one over-arching requirement for the portal itself. It contains 
things like style elements and the bits that are common across more than
one application, and then the major functional reqiurements of the thing
list each individual application or area of research or 'logically
separate functional thingy' unit, each of which gets their own
requirement.

Then you look at each 'separate functional thingy'. It has business rules
and functional requirements that govern it. Some of them have modules that
are themselves complex enough to get their own requirement. Some single
requirements (Generate a report of all Xes who fit conditions Y and Z 
in fiscal year NN) break down to 15 pages of details that are probably
best served by having their own document.

If no one has officially 'killed' the original document, get management to
do that immediately. Have it declared dead, put a stake through the
heart, cut off the head, burn it, and scatter the ashes. Make it
unavailable to the rest of the enterprise. What you need to do is make
sure no one else is using it for reference (or, worse yet, updating it)
while you're doctoring on the thing. If you can only do this in pieces,
that's still better than nothing. When someone adds a new requirement, you
need to grab ownership of those documentation pieces that go along with
it, and make sure it gets done right the first time, instead of it being
bolted on to another piece of this entirely broken thing they just handed
you. That only makes the problem worse.

In a year, I've documented the two largest modules of the two largest
applications (two 80+ -page requirements, 200 pages of user manuals, 50
pages of software test plans) and a couple dozen smaller pieces. In my
free time (yeah, right) I'm working on the big-picture documents, both
for the whole site and for the major applications on it. ...so,
day-to-day, you're attacking the problem from the bottom up, and when you
get a chance, you can do some work from the top down. 

Once you have individual pieces, or collections of individual pieces,
those can go into source control, either as text or HTML into CVS, onto a
web-based collaborative solution that has revision control on the back 
end like Twiki or SharePoint/VSS, or into a requirements tracking thing
like CompuWare Reconcile. I don't have a revision control thing set up
here yet, but I'll get there eventually. 

And that's how you kill five dragons.

-- 
Huey


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Robohelp X3, from eHelp, lets you quickly and easily create 
professional Help systems for all your Windows and Web-based 
applications, including Net. 

Order RoboHelp X3 in May and receive a $100 mail-in rebate, PLUS
free RoboScreenCapture and WebHelp Merge Module. 
 
Order RoboHelp today: http://www.ehelp.com/techwr-l

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