Source Code Control for Documentation

Jim Kring and Joel Sumner have posted recently about the benefits of source code control (SCC) for software development. At NI, the technical writers also use SCC for our documentation development. For those who are unfamiliar with SCC, it works like this:

• Your source files are stored in a repository on a central server.
• To edit a source file, you must "check out" the file. Checking out a file downloads a copy to your computer, where you then make your edits. Typically, checked-out files are marked as such so others cannot check them out at the same time.
  

(You can configure some SCC programs to allow multiple checked-out copies simultaneously. The SCC program then can merge multiple changes back into a single file. I tend to distrust this method; I much prefer the security of knowing I'm the only one with the file checked out for editing.)

• When you are done making edits, you check the file back in, which involves uploading it back into the central repository. Others can then synchronize to the latest version of the file that contains your edits, check out the file themselves, and repeat the process.
  

SCC for documentation, at least the way we do it at NI, has many benefits that parallel what Jim and Joel describe for software.

• Because only one person can check out a file at a time, SCC ensures you don't overwrite ("blap") edits that someone else made. This benefit mainly is for larger groups of writers that all work on the same source material, like in LabVIEW.
• Because the most recent copy of the file is stored in a central location, everyone knows where to go to get the freshest copy of all necessary files. Again, this benefit mainly applies to groups of technical writers.
  
• Ensuring you have the latest version of a file is as simple as right-clicking a file and selecting Sync to latest revision.
• SCC allows you rewind time back to when a file was good. If you check a file in and suddenly the XML won't transform or the HTML looks wonky, you can synchronize to a previous revision of the document when you know everything was good. The SCC program can handle this revision history automatically, so you don't need to spend time renaming files, copying files to different directories, or marking files as read-only.
  
• Some SCC programs feature an integrated tool for differentiating ("diffing") between versions of files. With the click of a button you can highlight differences between the document you're editing and what's stored on the server. This tool is really powerful for documentation because you can see exactly what changes someone else might have made to your document. (Or, if you're a lone writer, what changes you made to your document!) Because the changes are highlighted onscreen, you're not distracted by unchanged text.
  

For this to work, the file must be stored as text (XML, HTML, etc.) and not binary (FrameMaker, MS Word, etc).

• SCC allows you to annotate the changes you made every time you check in a file. These annotations can be as simple as "Fixed some typos," but more descriptive annotations are even more helpful. By clicking "Revision history" in Perforce, the SCC program NI uses, I can see who's done what to the file. Some file histories extend back to 2001 and provide a rich timeline of the file's evolution over time. This benefit helps not only large groups of writers, but even lone writers who want a quick record of what they've changed and when.

I find that the only drawback with SCC is the overhead of editing a single file, which involves the following steps:

1. Launching Perforce. (Actually, I usually keep it running.)
2. Navigating to the file's place in the repository. (This can be slightly time-consuming if the server is being slow, the file is located on a different server, or if the file is buried in a deep directory structure.)
3. Checking out the file.
4. Launching the program to edit the file.
5. Editing the file.
6. Saving the file.
7. Using Perforce to annotate the changes you've made.
8. Submitting the file.

Without Perforce, only the opening/editing/saving steps apply. But you then would lose the benefits of knowing that these changes are permanent, trackable, and eraseable. These benefits are essential in a mid-to-large size organization like NI.

Also, it can get confusing if you sync to a file and then delete it by using Windows Explorer. In this situation, the SCC program still thinks you have the latest copy of the file, so you have to remember to force the program to actually download the file again. But this is really more of a "user error" issue, although it crops up for me frequently as I install and uninstall various development versions of LabVIEW on my computer.

For those of you who want to give SCC a try without spending a dime, check out subversion or the Perforce evaluation.

Documentation is Important

Even our developers think so :-)

What We Do All Day, Part 2

Interested in working as a technical writer but don't know what it is that we do? Our Texas Tech recruiting team gathered some alumni and put together an informative video that consists of interviews with technical writers and managers here at NI. The video also has some great tips for those who are applying for technical writing jobs. Top tip: Proofread your resume! :-)