How do you reuse paragraphs?

Die Qual der Wahl“… it’s hard to choose, sometimes. There are many ways to apply reuse in DITA, or in other authoring environments. What would be the best way for a team to manage reused content, in case of similar topics with series of list items, table rows or just paragraphs?

The usual discourse in lectures, books and webinars I’ve seen, although using various names, compares methods like inclusion (referencing, insets) and conditioning.

Two reuse methods

To achieve the same results (publishing deliverables A, B, C), you can work with methods such as:

  • managing a warehouse topic, from where each author retrieves components by ID (conref or conkeyref, in DITA) and maintains individual topics for each project.
  • managing one common topic for all authors and applying conditions (attributes) on items specific to each project.

The first method obviously adds one intermediate stage, requiring each author to maintain parallel versions of the same topic. Apart from that, it depends on your policy, if you would see it as an advantage, that the authors can rearrange the items and even add extra content around them.

Although the second method brings the advantage of maintaining only one source, it adds more complexity at taxonomy level. The combinations of attribute values and the number of ditaval files or entries in the subject scheme map can become overwhelming.

There are other possibilities, of course. For example, to consider topic1.xml the master topic and to work with topic2.xml and topic3.xml as variants of 1, which means changes in topic1 would also influence the variant topics.

Thank you for your input.