TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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.
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
