It turns out that the moment a safety warning has to change, a part number has to change, or a product with a different control panel is shipped, the question becomes how many places in the documentation have to be changed and how many will get lost in the process.

To serve to answer these questions, DITA shifts the unit of work from documents to topics and from formatting to semantics. Each of these mechanisms has its own cost to use.

Topics as the unit of authorship, maps as the unit of delivery

A DITA topic is a chunk of content that is self-contained and has a declared type (such as Concept, Task, Reference). So Concept topics explain things. Task topics tell people how to do things. Reference topics list things. This typing at the topic level constrains the element model, so for example a Task topic cannot devolve into general prose. All of this automated validation and consistent output are possible only because we’ve defined these typing boundaries at the topic level.

A map is used to organize a set of topics into a single deliverable, such as a guide or manual. Maps represent the hierarchy, sequence and relationships between topics. Maps are separate from topics. This means that a single topic can be included in many different deliverables. The process of reorganizing a manual becomes simply a change to a map rather than a rewrite of content.

Why topic granularity is a design decision

Granularity of content also has a major impact on the level of reuse and thus on maintenance and even on the change management process within an organization. Large topics that cannot be used in other variants of a document cannot be reused for other documents. On the other hand, very small topics with only a few sentences might result in maps with thousands of entries, which would be virtually impossible to manage for a large team of authors.

Reuse mechanisms and their trade-offs

Reuse is actually formulated on several levels and therefore has to be chosen very carefully so as not to create maintenance nightmares which will surface long after the initial publication.

• Topic references pull a whole topic into multiple maps. They carry the lowest overhead and the highest payoff, so they are the default choice.
• Content references (conref) pull an element, such as a warning, a step, or a table row, from one topic into another. They are powerful, but heavily conrefed content becomes hard to read in the authoring tool.
• Keys and key references resolve product names, values, and links indirectly at build time. This is what allows one source set to produce documentation for several brands or model numbers.
• Conditional processing filters content by audience, platform, or product using attributes. It is cheap to apply and expensive to govern, because every new condition multiplies the output combinations that need testing.

What structured source does to translation economics

Translation, It’s where the ROI on structured content is typically realized. Since topics are stored as discrete files with stable IDs, Translation Management Systems can work off the changed topics only, as opposed to re-translating the entire document. A 10% change in content translates into a 10% change in translation spend, as opposed to a full re-review of the updated content.

The reuse of content further amplifies the return on investment from the structured content. A warning that is reused in 40 places is translated once and then reused in all 40 places. Content that is not required to be translated in a market can be excluded from the output for that market via conditional filtering.

Practical safeguards for localization

Conref and key resolution occur at build time, so fragments will often be translated without the surrounding text. It is useful to provide preview output of supplied resolved content, to keep translatable text out of attribute values wherever possible and to avoid constructing sentences by concatenating fragments together. Grammatical agreement rules for sentences constructed from conrefs differ by language and often will break in most languages when using concatenation.

Publishing pipelines and enterprise governance

It should fail the build if your documents are not up to date, not if they have been rendered incorrectly. Validate the DITA against the DITA Schema, validate the links, and validate the keys before applying conditions for each output. Using the DITA Open Architecture will enable you to leverage automated publishing by triggering DITA maps to publish documents automatically off of Version Control Systems.

Most organizations spend too little time thinking through specialization, names, metadata, ownership of shared content, and a process to deprecate content that should no longer be reused. Teams managing thousands of topics across many products are usually better served by an enterprise DITA CCMS, which enforces ownership, review workflow, and reuse tracking that a file repository alone cannot provide. Without such governance, the reuse network can become a target that nobody dares to touch.

Signals that the implementation is working

1. Time from source change to published output measured in minutes, not days.
2. Reuse ratio tracked and rising, with shared topics owned by named teams.
3. Translation word counts falling relative to content volume.
4. Build failures caught before review, not after publication.

DITA is not intended to reduce the amount of good writing, but it does reduce the cost of maintaining identical copy in 50 places. This is what limits large documentation sets to this extent.