Advice on document folder structure in ClearCase?

[Geoff Hart]

Lorraine Flynn wondered: <<I just got a new job as a (sole) writer  
for a large city software project. Their documents are scattered all  
over the place. They want to use RUP although the only RUP tool they  
are using is ClearCase. Can anyone suggest a good folder structure  
for documentation within ClearCase.>>

The people who will be using the structure should be your first and  
only source of information on what structure you should implement. In  
many years spent working in offices, it's become clear to me that my  
perfectly logical filing system is your disorganization nightmare,  
and vice versa--plus, our mutual boss undoubtedly thinks we're both  
crazy. <g> This means that if you want to create something effective,  
you should not impose your vision of reality on everyone else.

Since the users of the system are likely to vary in their opinions,  
you'll have two goals. First, look for similarities and recurring  
themes. These are areas where everyone agrees on the need for a  
category and the title for that category and the logic for what goes  
into each container. Use this as the core of your organizational  
pattern. Ideally, if you can analyze the work flow at your office,  
you'll see that it falls into clear groups of steps and tasks, and  
these groups will provide additional inspiration. If the structure  
matches how everyone works and how they think of their tasks, it will  
be understood and used. If not...

Note that the titles must be clear and distinct. You proposed the  
following headings: Business, Requirements, Project Management,  
Development, Testing and Quality, Deployment, End User, and Vendor  
Documents. Personally, not knowing the organizational context, I see  
considerable overlap among these categories. For example, is  
"requirements" part of "business" or part of "project management"? Is  
"development" really separate from "testing"? This kind of  
imprecision increases the proportion of documents that will be  
misfiled. Don't take this as harsh criticism: we can never make the  
categories perfectly clear, but we can make them clearer with a  
little help from the users.

Second, think "synonym". I don't know anything about ClearCase, but  
if it permits the use of synonyms, it may make very good sense to  
create two tiers of folder structure. Tier 1 is the structure you  
developed (above) based on the consensus about what subject areas and  
titles to use. This tier forms the actual physical directory  
structure on the server, and it represents consensus reality for  
_everyone_. Tier 2 should be customizable by the user, like using  
aliases on the Mac or shortcuts on Windows. If your "business"  
directory title makes no sense to a user, and they think of this  
container as "capitalist dogma" <g>, allowing them to use that title  
increases the likelihood that they'll file the documents in the right  
place.

Note that in practice, everyone is still using the identical Tier 1  
structure (i.e., the names on the server) or their own Tier 2  
structure (i.e., shortcuts on their own computer) to gain access to  
the files. This means you won't have to worry that allowing all these  
bizarre synonyms will lead to any filing problems. Moreover, it  
provides enormous flexibility: people can use whichever approach  
makes it easier for them to understand where to find and put things.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --

Geoff Hart   ghart at videotron.ca

(try geoffhart at mac.com if you don't get a reply)

www.geoff-hart.com

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -