Reusing snippets
Another scenario in reuse is where the unit of reuse is smaller than an entire topic. Common examples include:
- Product names
- Notes, Warnings, and Cautions
- Descriptions of common user actions
- Any sensitive text that has been vetted
There are several advantages to reuse in the case of snippets like these:
- Creative productivity--By this I mean not having to make up text time and time again. I differentiate this from productivity gains from not having to type the same text time and time again, because I'm not convinced that it takes less time to insert a cross reference than it would take to type it anew. The savings, in my mind, come from not having to recompose it each time.
- Revision efficiency--Oh yeah, when marketing decides the product is now WormBuster XL rather than WormBreaker: edit once, change many.
- Control--After two hours of arguing with legal and marketing how to warn the user that changing advanced parameters could crash their system if they make a typo, make sure that the vetted text is used everywhere.
- Consistency--If the drop down for selecting port protocol on this screen works just the same way as it works on 11 other screens, it is easier for the user to process and remember the instruction if it is the same for all 12 screens.
Guidelines
To reuse subtopic elements, you need a composition environment that allows you to identify components and insert them in topics as objects. In DITA, this is easy since DITA is a semantic markup XML implementation. Every tag has an ID attribute, so every element that can be tagged can be IDed and subsequently shared. The tag in DITA that allows you to insert content from another topic is called the content reference [conref]. Essentially it is a tag in one file that points to a tag in another file.
Ubiquity
The big caveat in DITA, however, is to use ubiquitous tags, that is, elements that can be used the most widely within the rules of the DTD (the rule-keeper of structured writing, essentially the defining document that says what can be used where).
For example, all DITA topics have a short description [shortdesc], but a topic can have only one [shortdesc]This means that if you want to reuse that short description elsewhere, you must give it a tag other than [shortdesc]. The phrase tag comes in handy there. You would tag your short description like this:
[shortdesc][ph id=sort_search]Use this dialog box to sort the order of your search results.[/ph][/shortdesc]
That way, you can grab that phrase and reuse it in other topics, even as the short description in other topics.
Corral your sources
A good practice is to create special files that contain your conref'ed phases or components. That way you do not have to go looking for them trying to remember what topic was the source of that well-phrased warning. It is useful to have specialized conref files, for example, a file for product names, a file for warnings and alerts, a file for UI components, etc.
Probably the best practice in this regard is to develop the discipline that the first time you decide to conref a phrase that you have already used in a topic, pull that phrase out of its original topic, put it in a conref source file, then conref it back into the original as well as the new topic. Not only does this preserve the integrity of single sourcing, it lets you rethink how you want to word that element now that you are throwing it into the reuse pool for others.
Avoid restrictive wording
This is pretty much the same guideline that we had for topics. Think reuse ahead of time. For example, if you are documenting a UI component that sets the source port for a firewall rule, and you know that same component is used elsewhere to define destination ports, avoid using the restrictions "source" or "destination" in the instruction. The user should pick that context up from the topics themselves, don't restrict the reuse of the instruction by repeating that restriction there.
No comments:
Post a Comment