Advice on document folder structure in ClearCase?

Subject: Advice on document folder structure in ClearCase?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>, lorraine -at- lorraineflynn -dot- com
Date: Thu, 05 Oct 2006 10:16:30 -0400

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 -dot- ca

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

www.geoff-hart.com

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


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

WebWorks ePublisher Pro for Word features support for every major Help format plus PDF, HTML and more. Flexible, precise, and efficient content delivery. Try it today! http://www.webworks.com/techwr-l

Easily create HTML or Microsoft Word content and convert to any popular Help file format or printed documentation. Learn more at http://www.DocToHelp.com/TechwrlList

---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
To unsubscribe send a blank email to techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.


Follow-Ups:

References:
Advice on document folder structure in ClearCase: From: lorraine

Previous by Author: Does quality documentation reduce call center cost?
Next by Author: Gathering feedback on the image annotation tool?
Previous by Thread: Advice on document folder structure in ClearCase
Next by Thread: Re: Advice on document folder structure in ClearCase?


What this post helpful? Share it with friends and colleagues:


Sponsored Ads