Questions in this FAQ list:
The Frequently Asked Questions for DITA have been collected from questions asked on the DITA Forum and among other communities. Some of the answers reflect DITA Best Practices.
General DITA questions
This architecture supports the proper construction of specialized DTDs from any higher-level DTD or schema. The base DTD is ditabase DTD, which contains an archetype topic structure and three additional peer topics that are typed specializations from the basic topic: concept, task, and reftopic. The principles of specialization and inheritance resemble the principle of variation in species proposed by Charles Darwin. So the name reminds us of the key extensibility mechanism inherent in the architecture.
Argus Center for Information Architecture 10 Questions about Information Architecture
DocBook was originally designed for a single, continuous technical narrative (where the narrative might be of article, book, or multi-volume length). Through transforms, DocBook can chunk this technical narrative into topics to provide support for Web sites and other information sets. Because the goal of the DocBook DTD is to handle all standard requirements for technical documentation, the usage model encourages customization to exclude elements that aren't local requirements. The usage model supports but discourages local extensions because of the potential for unknown new elements to break tool support and interoperability.
By contrast, DITA was designed for discrete technical topics. DITA collects topics into information sets, potentially using filtering criteria. The core DITA information types are not intended to cover all requirements but, instead, provide a base for meeting new requirements through extension. Extension is encouraged, but new elements must be recognizable as specializations of existing elements. Through generalization, DITA provides for tool reuse and interoperability.
Each approach has its strengths. DocBook would be the likely choice for a technical narrative. DITA would be the likely choice for large, complex collections of topics or for applications that require both extensibility and interoperability. Technical communications groups might want to experiment with both packages to determine which approach is better suited for their processes and outputs.
Use the DITA forum to discuss the use of the DITA DTDs and style sheets. The read-me document lists several known limitations, but doubtless others await discovery as you use the DTDs. Through discussion in the DITA forum, the significant ideas will be identified and applied to subsequent refreshes of the package. The forum will be actively monitored by the DITA project's architects, Don Day and Michael Priestley, among others.
The topic architecture of DITA
A topic can be augmented by a prolog, a short description, and other optional metadata. These conditions lead to the following structure:
<!ELEMENT topic (title, titlealts?, shortdesc?, prolog?, body, related-links?, (%info-types;)*)>
See the Sample topic, and its explanation, The structure of a DITA topic.
<topic> <title>A general topic</title> <shortdesc>This general topic is pretty general.</shortdesc> <body><p>General topics are not very specific. They are useful for the big picture, but they don't get into details in the same way as more specific topics.</p></body> <topic> <title>A specific topic</title> <shortdesc>This is a more specific topic.</shortdesc> <body><p>Specifically, this is more specific.</p></body> </topic> </topic>
You can author topics either as nested structures or as individual stand-alone documents. In the latter case, you assemble the documents into nested structures as required, such as when delivering printed or printable information that has a part and chapter hierarchy.
The nested structure gives a sequence and hierarchy of topics within a topic collection. In a Web environment you could disassemble this structure into individual topics and preserve the hierarchy in a generated navigation map or table of contents. However, if the Web is the main delivery vehicle, you might want to author the topics as separate documents and then apply several tables of contents to the same collection of topics.
Rules govern how to specialize safely: Each new information type must map to an existing one, and new information types must be more restrictive than the existing one in the content that they allow. With such specialization, new information types can use generic processing streams for translation, print, and Web publishing. Although a product group can override or extend these processes, they get the full range of existing processes by default, without any extra work or maintenance. The DITA specialization articles outline the rules for each kind of specialization (topic type and domain type).
Tips and techniques
DITA's conref "transclusion" mechanism is similar to the SGML conref mechanism, which uses an empty element as a reference to a complete element elsewhere. However, DITA requires that at least a minimal content model for the referencing element be present, and performs checks during processing to ensure that the replacement element is valid in its new context. This mechanism goes beyond standard XInclude, in that content can be incorporated only when it is equivalent: If there is a mismatch between the reusing and reused element types, the conref is not resolved. It also goes beyond standard entity reuse, in that it allows the reused content to be in a valid XML file with a DTD. The net result is that reused content gets validated at authoring time, rather than at reuse time, catching problems at their source.
Content referencing can be used at any scope of elements in a DITA document, from a keyword phrase that contains only PCDATA to a whole topic with other nested topics. Conref can cross file boundaries, using the same syntax as that of the href attribute on the xref element. If your authoring DTD allows topic nesting, you can create a set of minimal child topics and then use their conref attributes to pull in content from fully populated topics in other files.
When you specialize a domain, you need to first determine what elements must be specialized for the domain. Then you write an entity declaration file to list the specialized elements, along with their topic types and domain types. Next, you create a file where you define both the elements that are introduced for the domain and the specialization hierarchy. Finally, you write the shell DTD to combine the domain with topics and other domains.
These processes are described in more detail in the documents Specializing topics in DITA and Specializing domains in DITA.