DITA & XML Community of the Rockies

In his article, Getting Started [with DITA] as Cheaply as Possible, Eliot Kimber puts together a very impressive manifest of component pieces to a free or low-cost DITA content management system (CMS). This recipe has helped many small-to-medium sized companies realize a systematic, extensible approach to document management. It has also helped larger companies as they grow into more full-featured DITA CMSs. His article is not exhaustive, however. If it were, it would be a book(s) rather than an article.

I thought I’d wade in and expand the CMS portion of Eliot’s article that may help others interested in getting a DITA documentation system up and running. Here’s what Eliot writes about the CMS component of the DITA-based system:

Subversion is an open-source code control system that
functionally replaces CVS but offers several important new features,
including full support for versioning of binary objects (including UTF-8
and UTF-16-encoded XML), versioning of directories (very important for
DITA where you need flexibility to change how your topics are organized
as you refine your practices), HTTP-based access (avoids issues with
corporate firewalls), easy scripting, and arbitrary per-file metadata
(enables potentially quite sophisticated management features). There are
a number of good open-source and commercial Subversion clients,
including TortoiseSVN, Oxygen's Subversion client, and the subclipse
plug-in for Eclipse. Coupled with good file organization and naming discipline Subversion can get you a long way.

The four lodge poles of the any full-featured content management tepee are 1) the protection of your hard work by regression to earlier versions (version control), 2) a common repository where access is granted to those working with the source 3) the ability to build components from smaller components (modularization and reuse), and 4) the ability to find what you need fast (search and retrieval). Subversion handles #1 and #2 very well. These are Subversion’s intended purposes. #3 is taken care of to a large degree by the DITA architecture through the organization of topicrefs within a ditamap, strategic construction of topic relationships within a relationship table (reltable) and by the use of conrefs. #4 would require custom coding that is well beyond the scope of Subversion. One might handle search and retrieval by auto-indexing the source, which in addition to residing within a Subversion repository, lives within a free XQuery database such as eXist.

To set up the SVN repository on a server so that writers and developers will have access to it, you may want hand this task over to your company’s IT guy because this person should be no stranger to setting up, administering and securing a Subversion server. But wait, you say, I am the IT guy. I’m also the marketing guy, the writer guy, the coder guy, the sales guy and the guy-who-empties-the-office-trash-bin guy — and I don’t know how to set up an SVN repository on a LAN or I’ve never used version control in my life…. If this is you, no problem. A good place to start is the free (do you see a common thread here) online book called Version Control with Subversion or review the Wikipedia entry on Subversion.

If you plan to set up your SVN repository on an Ubuntu Linux server, then follow these instructions. For Windows, see these guidelines; however, I have not personally tested the Windows process. For those who choose to use a Mac OS as a server, check this out.

Alternatively, many Internet service providers (ISP) offer SVN repository service to their customers, which would take a minimum of configuration on your part because they will have done most of the heavy lifting for you. If you use an ISP and want to set up SVN for remote access but do not want to dedicate a server of your own, then this is something to look into. Instructions on how to set up an SVN repository vary for each ISP, so you’ll want to review your provider’s documentation for specifics. In fact, there are many ways to set up an SVN repository and a simple Google search on the keywords SVN, repository, and server will list other alternatives.

Even if you do not need remote user access to source now, you may want to keep your desktop and a laptop files synchronized. Or you may want to be more organized and keep versions and backups of your work off-site. Subversion helps you with both of these scenarios.

You may want to check out these tips on structuring your new subversion repository. There are also some worthwhile tidbits on structuring the repository directories on the video, VisualSVN: Setting up Subversion in just 4 minutes.

If it was not part of the repository setup process, import your initial source base into the repository. Mileage may vary on how to go about this, depending on which process you used. Read the documentation. If you have trouble with this step, contact us through the DITA & XML Community bulletin board and we should be able to help.

Now that a new SVN repository has been set up, it’s time to connect to it with an SVN client. Eliot mentions three such clients: TortoiseSVN, Oxygen’s Subversion client, and the Subclipse plugin for Eclipse. For reasons I will mention later, the Subclipse plugin is of most interest, but can be a little troublesome to set up without the right guidelines, so I’ll focus on it. I should mention that the venerable TortoiseSVN is free and well documented. If you have purchased a license for Oxygen XML Editor, then you may want to use its Syncro SVN Client, which can be accessed under the Tools menu of the Oxygen XML Editor.

NOTE: All aspects of SVN server-side and client-side administration can be done from a command line, so the aforementioned GUI-based tools are for convenience only.

To set up the Subclipse plugin in Eclipse 3.4.x, follow Frank’s instructions. This assumes that you have already downloaded the latest version of Eclipse. I use “Classic” at the bottom of the downloads list. Follow Frank’s steps closely. If you do, you will have saved yourself a lot of heartache by not following other Subclipse recipes out there on the Interwebs.

Once you have the necessary SVN plugins loaded into Eclipse, follow these instructions on how to configure Subclipse within Eclipse. You will find them in the table of contents under Subclipse – Subversion Eclipse Plugin.

At this point, you should have a working SVN repository on a server, source under SVN control, and an SVN client to connect to the repository so that you can make changes to a local working copy of your source. To commit your changes to the repository, assuming you are using Subclipse, right click on the appropriate file or directory within your Eclipse project, then drill into Team > Commit. Other SVN clients have slightly different ways to push changes back to the repository so that team members can pick them up and vice-versa. It will pay dividends to understand the life cycle terms of source control such as check out, update, commit, sync, etc.

I lean towards using the Subclipse plugin because of the benefits that extend beyond Eclipse’s ability to handle control source. Eclipse is also a powerful platform as an XML editor and information product builder. In fact, your entire DITA system can reside within Eclipse “for free”. For an open-source DITA editor and multichannel (XHTML, PDF, Eclipse plugins, etc.) builder, check out the DITA Open Platform Editor plugin for Eclipse. You can even use your new SVN capabilities to download the nightly build files of the DITA Open Platform Editor (DOPE), build it from source using Ant within Eclipse, and contribute to its development. I like DOPE. Give it a try and let me know what you think.

I believe the point that Eliot Kimber makes in his article is that an organization adopting DITA can go very far with free tools while maintaining the KISS philosophy. While the addition of Subversion is not necessary to your DITA system in the strictest sense, it only takes one failed hard drive to learn the value of keeping your source under source control. Version control takes some discipline to use on a consistent basis, but after a while it becomes part of the process. It may even enhance your quality of life because you will sleep easier at night knowing that your DITA files are safe. -Cheers.