A list of choices that a DITA project needs to consider.
Originally prepared in 2008.
Once you’ve decided that DITA is provides the benefits for your organization that outweigh the attendant costs, the next step is to begin building your DITA model.
What you need to know at the outset is that, like any complex software system, there are many ways to get the job done. Use this list as a guide. For each entry in the list, get the education you need to understand the basic terminology, and to evaluate the tradeoffs of each choice.
For your own sanity, make a document that has comparison tables for the different option, and that records the options you selected, and why. (Trust me. You’ll thank me later. Down the road, you’ll know exactly why you did things the way you did — which will make it possible either to justify the choice, or make a change, secure in the knowledge that your initial reasoning was off. Without that document, if there it looks like there is a need to change, it’s hard to be sure that changing is the right thing to do.)
Contents
Migration Options
- Sometimes, it makes the most sense to start from scratch, and rebuild your documentation from the ground up. Other times, it makes sense to migrate your existing documentation.
Learn more: Tips and Techniques for Migrating to DITA
Conversion Choices
- Convert existing information to specific topic types or to generic topics?
- If generic topics: Nest the topics themselves (like the original), or make separate topics and nest topicrefs in a map?
Structuring Choices
- File naming and directory structures
- Allow sections in topics, or not
- Put index terms in the body of the document or in the prologue
- Use conditionals or composition? (see related article)
- Use word-level phrases for variables or sentence-level phrases?
Metadata Choices
- Metadata Define all expected metadata at the outset, make a minimal set and plan to evolve it, or define the metadata you see yourself needing in the next couple of years and ignore everything else.
- Make “hierarchical” metadata (Product A_1…B_2) or use separate dimensions (Product=A, B. Version=1,2).
- Are metadata specializations needed?
- If so, does it make more sense to do domain attribute specialization, or use the <otherprops> element?
Linking Choices
- Keep links inline, in topics or restrict links to reltables?
- Include links to external documents or not?
- If including links to external documents, use absolute links with a version# entity ref in the link (https://location/product_&version;/file) or use a “doc root” entity ref in the link(&docroot;/path/to/file)?
Differencing Choices
- Use status elements, manually marking items as new and changed.
- Use diffs maintained by the CMS or version-control system (VCS).
- Use processing instructions to identify changes.
Processing Choices
- Formatting Strategy: Break formatting-template into sections and encode in XSLT for use as DITA OT arguments; or extract content from generated pages and insert into copy of template.
- Processing Mechanism: Use the Open Toolkit, use CMS production tools (if available), or use editor production tools
- Process Control: Always generate all docs, implement dependency-driven builds, or deliver documents dynamically, upon request.
Branding and Styling Choices
- Use CMS templating mechanisms, if available
- Otherwise:
- Add XSLT transforms to Open Toolkit processing
- Feed Open Toolkit output into downstream processes
- Find or build a template system, where you can modify a WYSIWYG template (for example) and auto-convert the template into XSLT transforms.
Learn more: RuDi – A Ruby-based System for DITA document generation
Specialization Choices
- Create specialized topics or use generic topics?
