Writing in DITA - Tip # 3

While authoring, I often need to refer to that specific directory, that particular URL, this specific file which resides in this specific directory. As the software development cycle progresses, names change (and how). By the time people are ready for bit freeze, I am out of my mind worrying if all the specific references I put in your doc are updated (specific references are more "consumable" by a user). But if I've had the time to plan, I'd have probably envisaged such a scenario and prepared myself. How? I give here two alternatives (there could be more but I don't know of them yet). And, because I am making a case for Alternative 2, I'll shoot down each of the examples that I give for Alternative 1.

Alternative 1

Do not use specifics. Talk in generic terms. Examples:

• From the Sun website, download the latest version of the Java Development Toolkit.
  Problem: For all you know, Sun might be acquired by Moon, and the JDK be renamed to Lunar NetBeams.
  
• In the installation directory of the software application, look for a file with a name that has a suffix that correspond to the product acronym as listed in the Offical Acronyms page of the software application.
  problem: Which software application? You said Package A was prerequisite for Package B so I downloaded both from your website and installed them and they seem to be installed in the same directory - the directory name is the name of your company. Which subdirectory of the installation directory? There are no files in the main directory. Where is the Acronyms page? The first three hits in Google lead me to pages not maintained by your company.
  

Alternative 2

Use the conref facility provided by DITA.
DITA is about content reuse.  We might as well rephrase that to say, "DITA is about reducing maintenance overheads". (<aside>The first sentence talks about a feature.  The second about a benefit. Users look for benefits (what's in it for me), not features.  Am a bit puzzled why so many techcomm people keep using the first sentence without, ah, repurposing it for the target audience.</aside>)

This is how I do it: I maintain a separate file called in which I have a bunch of text that I think are of a variable nature. Each chunk of reusable text is wrapped in a <ph> element and given an ID. Like this:

Then, in the main files, I just conref these <ph> chunks. The text comes out looking like this: