Best Practices

Tips and tricks for working directly with the DITA OT.

Create targets only for document types that you need.

DITA-OT's most attractive feature is its ability to produce so many different types of documents from the same source files. However, you may find that you need to tweak the targets in your Ant build file to get a document to meet your customization and style guide requirements. Although the sample documents for DITA-OT ship with every available target, there is no point in ironing out the details of a dita2rtf target in your build file if your documentation set doesn't require Word-based documents. If you're not providing JavaHelp, troff, or .rtf, then don't create targets for them.

Place all content inside or within the map directory if HTML Help is one of your output types.

The HTML Help Compiler cannot compile the files generated by DITA-OT for source files that reside outside the folder where your .ditamap file resides. If your documentation suite contains HTML Help, you should place all your source files in or below this directory.

For advanced debugging, use a different temp folder for each document type within the same build.

The Ant build script for the DITA-OT samples uses a unique folder for each build. However, many builds will include multiple targets, and some of these targets generate overlapping intermediate files. Specify a unique temp directory for each target within the same build to be sure that the intermediate files that you are reading were generated for the target you're debugging. See the build file for this document for an example.