Reusable Components in Structured Authoring
© Ugur Akinci
It is useful to take an inventory of all the reusable components (text strings) in your technical documents as a prelude to structured authoring. Whether you use DocBook, DITA, or some other XML-based system, identifying the reusable components in your documents is an important prerequisite before you make the switch to XML-based authoring.
The higher the number of such components the more efficient will be your XML single-sourcing but at a cost: if all you have is nothing but reusable components then it means you’re not really conveying any unique information to your end users. So there’s a delicate balance there between efficiency and information content that you have to determine on a case-by-case basis.
Here are some samples of the kind of reusable components (text strings) that you can use in your structured
- Click OK to save.
- Select OK to continue.
- Follow these steps:
- Click <THIS> to display the <THAT> screen.
- Select <THIS> to <DO> <THAT>.
- Selecting and installing packages
- How to upgrade your system
- The operator should call the system administrator
The main idea is to write these strings only once and then to use them over and over again in different parts of the same document, and in different single-sourced versions (printed book, PDF, help file, mobile edition, etc.) of the same document. That would of course save the writer a lot of time and energy compared to writing (or copying and pasting) the same strings over and over again.
You can also embed such strings with “variables” defined in another file within the structured authoring environment.
For example, the string “The <PRODUCT NAME> comes with a <NUMBER> month guarantee” can be updated easily all across the document (and platforms on which it is published/broadcast) by simply changing the value of the “product name” and “number” variables at the source file.
This is very similar to switching your design variables instantly if you are using CSS (Cascading Style Sheet) in a design project. Changing the value of a string variable at a single source and then broadcasting the changed value all across the system instantly is both the most efficient and elegant way of updating your documents.
