Revision of Collected FAQs from Wed, 2006-03-22 01:47

Q: Is there a technical requirement for the single-file per topic attribute of DITA ?  (HTML can handle multiple topics per file, not sure why DITA doesn't.)

A: (Don Day) Be assured that DITA indeed allows multiple topics per file!  You might be confusing a best practice as a limitation of the architecture.

A topic is a chunk of discourse that supports a topical theme, which is usually expressed by the heading for that chunk.  HTML supports multiple levels of heading, so in this sense, it can contain multiple levels of topics.  However, in HTML, these "topics" are not bounded--the apparent relationship of the discourse to the heading is purely something that readers understand by convention, and the hierarchy is only visually implied through font sizes.  DITA also allows heading hierarchies through nesting--any topic type can nest additional topics of the same type. But in DITA, these topics are independently selectable units, unlike HTML.  And when using the ditabase DTD, you can actually nest topics of different types, as you might need to when writing an article or other more extensive kind of deliverable that is not, strictly speaking, an information unit for a help system.

Now, it is a best practice for writers of User Assistance, whether using HTML or DITA, to create only one topic per file.  This is so that the help system can fit the information to the task that the user is trying to perform at the moment.  In DITA, the ditamap represents the navigation that you want to present to the user, and this map lets you associate  various DITA topics in any preferred sequence or hierarchy.  In this sense, a nested DITA topic is exactly equivalent to a ditamap tree of the same topics separated out into individual files, but these separate topics have the advantage that they can be rearranged or selected through the map, whereas the single file of nested topics is always fixed in structure--you must edit the structure to change the sequence and hierarchy when using it as a single information unit.

If you prefer to create multiple DITA topics within a single file for ease of checkout and authoring new, related information, again consider using the ditabase DTD, which will allow you to create both peer topics AND nesting of topics within the top-level <dita> container.  These are still individually addressable through a DITA map, although you may find after you really get going that the separate file-per-topic practice is easier to manage once you get into production phase.
XML.org Focus Areas: BPEL | DITA | ebXML | IDtrust | OpenDocument | SAML | UBL | UDDI
OASIS sites: OASIS | Cover Pages | XML.org | AMQP | CGM Open | eGov | Emergency | IDtrust | LegalXML | Open CSA | OSLC | WS-I