Re: Version control advice (long)

["Dick Margulis " <margulis -at- mail -dot- fiam -dot- net>]

WW,

Here is one approach I like. YMMV.

Begin by sketching out a really good table of contents. A whiteboard or a yellow legal pad will do at this point. You need only go one level deep, but put some thought into what the dividing line is between documents. I think you probably want it to be between different sections of the site (from the user's perspective), but it may make more sense to you to divvy up the documents on technology lines. That's between you and your boss.

Next, implement the TOC as a spreadsheet (or possibly a simple database, although that is probably overkill).

You want your table to include some or all of the following information in each row:

Number (book, volume, chapter, section, whatever you end up calling the separate docs)

Version (there will be a separate line entry for every revision)

Title

Author(s)

Role A (reviewer? editor? approver? whatever your process requires)

Role B 

...

Role n

Date A (date checked out, date started, date completed, whatever dates your process requires you to keep track of)

Date B

...

Date n

Predecessor(s) (If document X changes, this guy needs to be reviewed)

Dependencies (If this guy changes, document Y needs to be reviewed)

Status (WIP, complete, superseded)

Checked out by (who has it right now)

Notes (enough room to briefly describe the contents, if your titles tend to be cryptic)

Path or link to document folder


Next, in whatever system you are working with (including just creating directories manually in Windows, if that's what you end up with), create a folder hierarchy:

At the top level is the overall project title ("Site Requirements," perhaps). Inside this you have your TOC spreadsheet or database file and a folder for each of the sections, labeled with the ID number only.

Within each section folder, you have a folder called "images," a folder called "active," a folder called "WIP," and a folder called "superseded."

In the "active" folder, you have the latest approved version of the document. In the "superseded" folder you have all prior versions. All these document filenames (for a given section) begin with the section number and are the same except for the terminal letter, which progresses from A (or you could use two-digit sequence numbers if you prefer). So you might have 01_SiteArchitecture_A, etc.

Link all images. When you move a doc from the "WIP" to the "active" folder or from there to the "superseded" folder, the links should remain intact (test this assertion). When an image changes while you are working on a revision, it just replaces the old image. When an image changes between revisions (that is, the change is part of the doc revision), give the image a new filename--numbers help). If the same image is used in different sections, store separate copies in the different "images" folders.

The last element is optional. That is a master index for all the images. Depending on the complexity of your site and how graphics-intense it is, you may need to invest in an asset management system; but it doesn't sound like you need to go to that extreme.

HTH,

Dick

---------- Original Message ----------------------------------
From: "Writer Whirler" <a_whirler -at- hotmail -dot- com>
Reply-To: "Writer Whirler" <a_whirler -at- hotmail -dot- com>
Date:  Thu, 05 Jun 2003 13:56:39 -0500

>
>Oh, you gurus of all things documentation..I seek your advice about how to 
>control an uncontrollable document.
>
>

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

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.