Should I set my root element to <dita> or <concept> (or <task> or <reference>)?

Contributing author: Don Day

Date: 2006

Using <dita> as your root element (which is the default behavior for FrameMaker DITA Edition and XMetaL DITA Edition) provides the following benefits for DITA information planners:


The key disadvantages of relying on the <dita> wrapper consistently is that the topics within it cannot be topicref'ed individually to be output as their own nodes in a map.This behavior is consistent for the occasional overview topic with dedicated content, but in general you would prefer individual topics for best ease of reuse. (This behavior is the default for XMLmind and Serna.)

DITA Open Toolkit is agnostic to any starting element, as long as it is either a map, a topic, a specialization of either, or a <dita> file. All outputs produce intermediate, fully-resolved topics in the temp directory. But whereas the HTML-based transforms that produce standalone result files work directly on these intermediate topics, the aggregation-based outputs (FO and RTF) do a subsequent topicmerge step into a single intermediate file as input to their respective final transforms. Again, as long as the process starts with anything that is ostensibly a map or topic, a "correct" output in terms of its own top-level structure will result.

A <dita> file always results in a single deliverable, whether processed by reference in a map or individually from the command line. When you process a <dita> file with peer topics to HTML, it will produce a single, well-formed HTML file in which the content of the peer topics show as a sequence of <h1> titles followed by their respective content. In other words, it is still a valid output, but the HTML deliverable is always a single output instance, following the input file structure.

One way to use this behavior to some advantage is to reference the contained topics via conref, liberating them for reuse in different sequences. For example, you can rearrange the sequences in this construction, and thereby change the order (or even the optionality of inclusion) of what the standalone <dita> file produces.
<dita>
<topic conref="sometopic.dita#sometarget"><title/></topic>
<topic conref="othertopic.dita#othertarget"><title/></topic>
...
<topic conref="end.dita#last"><title/></topic>
</dita>
		

Obviously, to achieve this "aggregated maplet" advantage, you must have separated those topics as standalone chunks in the first place. The result will still be a single output instance, unlike true map topicrefs. But you can change the order as needed, and conditionalize the conref even. Your analysis of the information architecture will lead to deciding which of the possible arrangements is best for your situation. Of the possibilities I've mentioned, all are "preferred roots" if the design so requires. You as an author should request that your authoring tool of choice allows you to manage the DITA architecture as needed.