Writing for re-use

You should embrace a style or method of writing that produces content suitable for re-use. This method includes an aim to minimise context.

In a linear writing environment, you tend to write in the context of the document you are creating. In modular writing, the writing needs to be removed from the context of its use. A modular topic might be used in different manuals, and in entirely different contexts. A description of a memory card may end up in a camera manual, a Netbook Help system, and a mobile phone Web-based user guide.

In DITA, any taggable element can be re-used through the conref mechanism. This means that paragraphs (block elements) or phrases (inline elements) can be re-used. For example, a note block might be used in multiple topics, and even more than once in an individual topic. Likewise, a procedural step, or a product name, might be a re-usable element.

In a DITA authoring environment, you must therefore assume that almost everything you write may end up being re-used elsewhere. You must avoid including context in your writing, as context restricts the ability to re-use.

For example, you should avoid phrasing such as in the following paragraphs, or as discussed earlier, or in the diagram below.

You should also avoid using restrictive references where possible. For example, a step command such as Click Print in the navigation pane on the left restricts the re-use of that step to cases where the Print button is located in the navigation pane on the left. While Click Print or Click Print in the navigation panel might sacrifice a little clarity, the benefits of re-use (including editing and translation efficiency) are usually worth the trade.

It could be argued that making compromises to writing style in order to improve the opportunities for re-use results in poorer writing. However, the writing of technical documents is inextricably linked with the business requirements of budgets and deadlines. Trade-offs are common in technical documentation, so the trade-off between writing style and re-use is just another.