RE: Version control advice (long)

[Rose -dot- Wilcox -at- pinnaclewest -dot- com]

<<I don't know much about ClearCase (we use it 
for code, but haven't used it for documentation, as far as I know.) 
ClearCase is fine with me, although any opinions there would be welcome, 
too.>>

ClearCase is fine for documentation version control.

<<The real dilemma for me is this:  Since I will be splitting up the doc into 
smaller pieces, how do I label them? The big document was produced as a 
baseline for a major release (2.0) of the portal. Some of these documents 
won't have changed at all since that release a few months back. Some will 
have changed a bunch, some not very much...you get the idea.

Should they all be labeled with the current release number (like 2.1.8, 2.2, 
etc.)? Or does labelling something imply that something inside of it 
changed? What about my boss's suggestion that each document have its own 
version number (Doc A = 2.0, Doc B = 2.3, Doc C = 2.3.1) that changes when 
something inside that document changes?

Whatever we decide to do, I want to start off on the right foot. Thanks in 
advance.

WW>>

For the version control piece, if you use ClearCase, you don't really need to do version numbering in the document name, since ClearCase will allow you to get to any previously saved version of the document of the same name.  (You can then do compares and/or replace the current document with the old document, etc.)

What you want is something that communicates to the reader what they need to know about the document.  Will the readers al have access to the documents in ClearCase?  If so, you can simply name the documents by topic and will not need to keep a version number in the name.  Readers can access a document knowing that whatever they pull up is the current version.  And if you need to go back in versions, ClearCase will let you do that.  You may want to include a Change Control section in the document listing what has changed since the last version.

If you want a visual change of name per document you might want to include the portal release *and* the document version *both* in the name.  The advantages of this is that it will group all the docs for the portal release together, even if the requirements document changes in between releases.  The disadvantage is that it is a lot of numbers, and people don't respond well to so many numbers.

If this numbering scheme seems to complicated, I would go with the document version in the name but keep the portal release somewhere on the front page and maybe even in the header/footer.  This depends on who is using the Requirements and what their needs are. You didn't include a lot of audience analysis in your post.

If you change the name of the document per version, you are doing version control manually, rather than using ClearCase's automatic feature, but it depends on what you need for your audience.

Rose A. Wilcox
CHQ, 17th Floor
Tranz1 QA/Documentation
602-250-2435
Rose -dot- Wilcox -at- PinnacleWest -dot- com

As Henry James said, "Three things in human life are important: the first is to be kind; the second is to be kind; and the third is to be kind."







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

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.