file:///C|/Documents%20and%20Settings/avaughan/Desktop/getstart/la...l%20-%20How%20Technical%20Writers%20Use%20Rational%20ClearCase.htm
How Technical Writers Use Rational ClearCase By Liz Augustine Every few weeks, one of my technical writing colleagues sends me a message like this one: "Help! Our group is starting to use Rational ClearCase! How do you recommend that the writers here set up a workable ClearCase environment?" This article attempts to answer that question.
What Are Some Key Benefits of Using Rational ClearCase? Technical writers, like software developers, use Rational ClearCase to track changes to their work and to ensure that they can reliably repeat the development processes that their group follows. For example, many writers who don't work with Rational ClearCase report confusion when they hand their work off to an editor. It can sometimes be hard to determine which is the latest set of files. It can also be hard to prevent two people from making changes to the same file at the same time. When you work with Rational ClearCase, you don't have to worry about these issues. ClearCase tracks each version for you so that you always know which one is the latest. And if someone else is working on a file, ClearCase tells you, letting you decide -- before you make changes -- whether you want to proceed.
The advantages of using Rational ClearCase became crystal clear to me a few months ago, when a manager told me that it was finally time for translators to start localizing our documentation for Rational customers around the globe. The only problem was that her team wanted to start with the files we had finished three months earlier -- and we had already started work on our next release. Using a traditional system, this would have been a disaster. The three-month-old files would already be overwritten or hard to find. Even with an undisciplined use of a configuration management program, the
About Rational ClearCase Rational ClearCase is a configuration management system designed to help software development teams track the files and directories they use to create software. ClearCase helps you manage the development and build process and enforce site-specific development policies. Rational ClearCase stores its files and directories in a database called a VOB
file:///C|/Documents%20and%20Settings/avaughan...cal%20Writers%20Use%20Rational%20ClearCase.htm (1 of 6) [4/8/2004 11:54:16 AM]
file:///C|/Documents%20and%20Settings/avaughan/Desktop/getstart/la...l%20-%20How%20Technical%20Writers%20Use%20Rational%20ClearCase.htm
situation wouldn't have been much better -- it would have taken days, if not weeks, to sort out. Because we were using some simple features of Rational ClearCase (labeling, which I'll describe later), I was able to give the manager access to the correct files within minutes.
How Do Writers Typically Use Rational ClearCase? Writers typically use Rational ClearCase to store source material - the files that we edit in order to produce books, Help files, and other material. For example, in your daily work, you might work with Adobe FrameMaker, Microsoft Word, Microsoft FrontPage, ForeFront ForeHelp, or eHelp RoboHelp.
(Versioned Object Base). For each file or directory, ClearCase keeps track of each version you create. How does Rational ClearCase know which version of each file you want to work with? You use a ClearCase view to select one version of each file or directory to use in your workspace. When you create a view, ClearCase creates a default configuration that shows you the latest version. Most writers I know use this default view and never have to change it. Rational ClearCase stores files so that you always have access to them. You can do anything you want to a file (open it, print it) until you want to make permanent changes. At that point, you check out the file, edit it and save your changes, then check in the file. This set of changes becomes the next version, and you start the cycle again.
Because writers usually work with tools that produce binary files (think Word's .doc files or Frame's .fm files), we don't typically work in parallel. That is, writers tend to organize their work so that just one person works on a file at a time. In this respect we diverge from software developers who primarily work with text-based files when they write code. In fact, it's quite common for developers to work in parallel -- they use Rational ClearCase's branching and merging capabilities so that two people can work on the same file at the same time. As a result, developers tend to have a more complicated approach to using Rational ClearCase, and they may encourage writers to adopt the same approach. In most situations, though, you can usually use ClearCase in its simplest form, working on the "main" line of development, and never using branches. At Rational, my group keeps documentation files in a VOB that we've nicknamed the doc VOB. We tend to have our own, private VOB because we work differently from the developers. Although these details may sound complicated, you can pick up the basic concepts very quickly. I make some recommendations about getting started at the end of this article.
How Do You Organize the Directory Structure? There are many ways to organize directories in a doc VOB, and the ultimate correct approach is the one file:///C|/Documents%20and%20Settings/avaughan...cal%20Writers%20Use%20Rational%20ClearCase.htm (2 of 6) [4/8/2004 11:54:16 AM]
file:///C|/Documents%20and%20Settings/avaughan/Desktop/getstart/la...l%20-%20How%20Technical%20Writers%20Use%20Rational%20ClearCase.htm
that works for your group. We have found that the following structure works well for us:
Directory
Comments
common
Contains files that are shared by more than one book. For example, this directory might be a good home for a preface boilerplate, your copyright page, and so on.
L10N.I18N
Contains files related to localization (L, 10 letters, and N), and internationalization (I, 18 letters, and N).
projects
Contains files related to non-deliverable projects, such as infrastructure.
release-notes
It would be nice to eliminate these, but we seem to need them in every release.
templates
Contains our group's templates, the files that give our documentation visual consistency. Subdirectories might be online and print.
online-help
Contains one subdirectory for each online help project, for example, install and licensing.
We place files for each book in their own top-level directory. We name the book directories so that it's easy to guess at their contents. Book directories sometimes contain planning documents as well as the book files; your group needs to decide what works best.
Note that this structure assumes you are working on just one product. If you work on a larger project in which you are creating more than one product, you might want to organize your VOB so that the top level contains directories for each product plus some of the project-related directories (for example, common, L10N.I18N, projects, templates). Subdirectories under each product directory would contain books and online help.
What Files Do You Keep in Rational ClearCase? You usually keep source files in Rational ClearCase. In fact, ClearCase is sometimes called a source control system. The types of files you store in the doc VOB depend on the tools you are using. Here are some examples:
file:///C|/Documents%20and%20Settings/avaughan...cal%20Writers%20Use%20Rational%20ClearCase.htm (3 of 6) [4/8/2004 11:54:16 AM]
file:///C|/Documents%20and%20Settings/avaughan/Desktop/getstart/la...l%20-%20How%20Technical%20Writers%20Use%20Rational%20ClearCase.htm
Tool
Files to Keep Under Source Control
Adobe FrameMaker
.fm (Frame files) .book (book files) graphics and other files included by reference into your book
Microsoft Word
.doc (the basic Word file)
Forefront ForeHelp
.fhb
eHelp RoboHelp
.rtf (the Rich Text Format file that you edit) .hpj (Winhelp project file) graphics files that you use with your help project
These tools create additional files; because you don't need these files to re-create the final product, there's no need to keep them under source control. For example, you don't need to keep backup files or files that your tools create during an intermediate step of a build. And you don't need to keep final results (such as .hlp files) in your doc VOB because your tools generate these files, and you don't edit them after they're created. (You may want to keep final results in a staging VOB if your group uses one; I discuss staging below.)
Hints for Using Rational ClearCase Here are a few hints for successfully using Rational ClearCase on a daily basis: ●
●
●
When you are about to edit a file, check it out. Technically, you can always edit a file without first checking it out; you just need to check out a file when you're ready to save it. However, performing a checkout before you start editing helps you avoid collisions with other writers who might want to work on the same file. Check in your files frequently, either when you reach a minor milestone, or at least every couple of days. Performing a check-in creates a record of your work, should you decide to restart from an earlier point. Also, files stored in Rational ClearCase are often backed up with greater regularity than are files stored on individual workstations. So checking in files provides greater security for your work. Always open and work on files in your Rational ClearCase view; don't copy your files to a nonClearCase directory to work on them. When you work around ClearCase, you also work around the protections that ClearCase provides for you. For example, once you make a copy of a file stored in ClearCase, you now have the old problem of figuring out which file is the most recent or
file:///C|/Documents%20and%20Settings/avaughan...cal%20Writers%20Use%20Rational%20ClearCase.htm (4 of 6) [4/8/2004 11:54:16 AM]
file:///C|/Documents%20and%20Settings/avaughan/Desktop/getstart/la...l%20-%20How%20Technical%20Writers%20Use%20Rational%20ClearCase.htm
which is the one you should be working with.
How Do You Use Rational ClearCase for "Staging"? Your release engineers are responsible for gathering all the files produced by your group and then creating a final product. They might build software into libraries (DLLs) or executables (EXEs). They also need to incorporate files that the writers on your team want to deliver to customers. To pass these files around, we use what we call a "staging" VOB, a separate area that contains just the finished files that will become part of a build. In some groups, release engineers build files for the writers. In our group, however, the writers build their own files. Once we test the files, we check out the previous version from the staging VOB, copy our built files over the checked-out files, and check in the new files. In our group, we usually stage online help files (.hlp and .cnt) and built book files, which we deliver to the customer as .pdf files. Why go to all this trouble? First, when you use a staging VOB, you always know that your release engineers are building the product with the right version of each file. And second, by using a staging VOB, your release engineers can always reliably recreate a version of your product, no matter how many versions you've built since.
When Should You Label Files? A label is just a human-readable marker on one version of a file. I recommend that you label files (and directories containing the files) when you reach a major milestone such as a beta or final release. Your set of labels provides a trail of breadcrumbs that allows you to retrieve an entire release-worth of source files, then re-create the final files for that release. For example, if the code names for your releases are based on types of bread, you might have the following labels in your VOB: ● ● ●
RYE_ALPHA, RYE_BETA, RYE_FINAL MARBLE_ALPHA, MARBLE_BETA1, MARBLE_BETA2, MARBLE_FINAL ANADAMA_BETA, ANADAMA_FINAL
This is one area where you want to exercise consistent discipline: label your files as soon as you reach your milestone. Otherwise, you will spend much time trying to recapture a past release.
Where Do You Go From Here? file:///C|/Documents%20and%20Settings/avaughan...cal%20Writers%20Use%20Rational%20ClearCase.htm (5 of 6) [4/8/2004 11:54:16 AM]
file:///C|/Documents%20and%20Settings/avaughan/Desktop/getstart/la...l%20-%20How%20Technical%20Writers%20Use%20Rational%20ClearCase.htm
So now what? How do you get started? I recommend these starting points: ●
● ●
Take the Rational ClearCase tutorial, which will give you a good foundation in the basics you'll need as you use ClearCase every day. Take a Rational ClearCase training course Work with the Rational ClearCase experts in your group to get help with setting up your environment. These experts might include your release engineer, your buildmeister, a project leader, or what we here call "the resident smart person."
Good luck!
file:///C|/Documents%20and%20Settings/avaughan...cal%20Writers%20Use%20Rational%20ClearCase.htm (6 of 6) [4/8/2004 11:54:16 AM]
