The most common applications are where some snippet, phrase, or instruction would be different depending on the OS or reader role. For example, have an instruction say ,"Click Start > Shutdown" for the Windows version of a manual and for Mac say, "Oh get over yourselves." (Sorry, couldn't resist that one.)
In DITA, you do this with ditaval properties and a separate .ditaval file that implements the conditionality when the ditamap processes the document. The main tip I have on that is to comment in the ditamap what ditaval files to run for what conditions. Sometimes we forget that others must follow us and will need the path blazed (also, when we come back to that file 12 months later we won't have the foggiest idea what we did).
Conditional text can let you get a lot of reuse out of instructions that have slightly different commands within a few steps. It can become a slippery slope, however, that can take you from writer to programmer if you're not careful. I have heard of some conditional strings in that no one could untangle after the original author ever left. The conditional text was trying to deal with multiple products and multiple audiences at the same time, or something like that, I believe. It certainly made editing and testing a challenge as well.
This ends my series of blogs on reuse. It's been helpful for me to reflect; thank you for your patience.
I made this joke up
An editor, a tech comm manager, a professor of technical communication, and a techical writer go into a bar. The bartender asks, "What are you having?"
The editor says, "At the moment nothing."
The manager asks, "What do you have?"
The professor asks, "What are others having?"
The tech writer says, "<step><cmd>Give me a <uicontrol>beer</uicontrol></cmd></step>"
No comments:
Post a Comment