Section 8.2. Documents and SCM


8.2. Documents and SCM

Anyone who has ever written even a small technical specification or article knows how useful it is to be able to look at earlier versions of the document. All the same reasons that developers keep track of source code changes with SCM tools apply to documentation: backing out unwanted changes and mistakes, coordinating your work with that done by other people, and recording the documentation as it was at the time of a release.

There are some SCM-related problems that occur more commonly when using an SCM tool to store documentation. First, the file format of many documents may be binary rather than text-based, and this makes merging from branches and integrating other people's changes more complex. Second, binary files are often much larger than text files, so the space demands on the SCM tool are larger.

Other issues are more psychological. For instance, documentation of a product's API is often generated from comments embedded in the source code. Javadoc (see Section 8.8, later in this chapter) is one example of a tool that uses this idea. The problem is that when the API documentation is reviewed, making the recommended changes to the documentation may involve editing large numbers of files, and these files are no doubt tightly controlled as the release date approaches. One way to avoid making accidental functional changes to the source code during these edits is to use a tool such as diff to confirm before the commit that all the changes are related to documentation. There are similar difference-checking tools for most documentation formats, either standalone or as part of the main editing tool.

Even if the file format for the documentation is binary and your SCM tool doesn't support showing the differences between two versions of a binary file, it's still worth using an SCM tool to track your documentation. First, the documentation files will be backed up with the rest of the source code for the product. Second, the SCM tool will let you recover the documentation as it was at any time in the past. This is another reason to avoid directories with names such as version_1.0, version_1.1, and version_2.0. Embedding the version name in an SCM-controlled filename or directory name is counter to the whole idea of using SCM.

For longer-lasting archives of your documentation, the files for each release to customers should be copied to CDs or DVDs, which should last for up to 10 years. If you want your documentation to last much longer than that, use a format-independent storage medium: print it out. With luck, those copies will make it to the next millennium, and the process of scanning printed text back into files will have advanced still further. Section 10.1 discusses how to archive your documentation environment in more detail.



Practical Development Environments
Practical Development Environments
ISBN: 0596007965
EAN: 2147483647
Year: 2004
Pages: 150

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net