Quick and rude guide to DITA OT installation

The install guide that comes with the DITA OT package is good (really, no sarcasm) but it sometimes assumes I am more of a techie than I really am. Last week, I changed my computer. It was while setting up my DITA environment that I remembered again that if I just follow these instructions to the T (see picture), I am more than likely to stumble.

So, I am writing up this blog post as a note to (i) myself, should I need to do this all over again (ii) everyone of you who wants to set up a DITA environment with minimal fuss. (<aside>I know; "minimal" is subjective.</aside>)

I use a Windows machine; these instructions are for a Windows setup (64-bit).

1. Download JDK. The latest version is JDK 6 Update 18 and can be downloaded from http://java.sun.com/javase/downloads/index.jsp. The file I downloaded is called jdk-6u18-windows-i586.exe.
2. Install JDK to a directory of your choice. To do so, double-click the jdk-6u18-windows-i586.exe file and follow the onscreen instructions. Stick to the default options. For the remaining part of this procedure, let's assume the JDK installation directory is C:\Program Files (x86)\Java\jdk1.6.0_18.
3. Download HTML Help Workshop. The file is called htmlhelp.exe and can be downloaded from http://www.microsoft.com/downloads/details.aspx?FamilyID=00535334-c8a6-452f-9aa0-d597d16580cc&displaylang=en.
4. Install HTML Help Workshop. To do so, double-click the htmlhelp.exe file and follow the onscreen instructions. Stick to the default options.
5. Download the full DITA OT package. The latest stable version is 1.5 and can be downloaded from http://sourceforge.net/projects/dita-ot. The file I downloaded is called DITA-OT1.5.1_full_easy_install_bin.zip.
6. Extract the contents of the DITA OT package to any directory of your choice. For the remaining part of this proceudre, let's assume this directory to be C:\Work_Area\DITA.
7. In the C:\Work_Area\DITA directory, look for a file called startcmd.bat, and double-click it.
8. In the command line window that opens, set the JAVA_HOME environment variable by running the following command: set JAVA_HOME=C:\Program Files (x86)\Java\jdk1.6.0_18
9. In the same command line window, test your DITA OT installation by running the following command (which is an ANT command for transforming DITA files): ant samples.web -f build_demo.xml Wait for the command to get over.
10. Return to Windows Explorer and, in the C:\Work_Area\DITA directory, look for a folder called out. This folder was created as a result of the previous step and contains the transformed files. If you cannot find this folder, something went wrong with the installation :-(

Notes for subsequent transforms: Set the Java environment variables every time you run an ANT build, and do it from the directory where the ANT build is being run.

Related posts
Now that DITA OT is installed, you might want to get yourself an authoring tool? See this blogpost: DITA authoring tool.
Next, you might want to run your transforms, no, not through the command line, but through a GUI? My next blog post is about such a transform tool: DITA tools - 3 (Publishing).

Post script
The procedure I wrote contains several inline links, and references to specific software versions and local directories. As any writer knows, these are maintenance headaches. Whether docs can (or, should) really have such specific info, and, if yes, how to include such info with minimal maintenance overheads is explored in this blog post: Writing in DITA - Tip #3.