Sunday, October 5, 2014

Best Practice--The conref file

As I mentioned in an earlier post, the conref attribute is one of the most useful tools DITA has for reuse. (See Reuse--The conref attribute.) Conrefs allow you to refer to an element and use its content in place of the current element. 

Usually, you will use the conref attribute to reuse lists, steps, notes, and product names. You can even use conrefs on whole paragraphs and tables. As most writers are painfully aware, product names, GUI labels, and object names are constantly changing throughout the development process. And, therefore, they make excellent candidates for conrefs. 

As a best practice, set up a file that is designated just for that purpose. That is, put your entire source for names in a conref file. (You can use the generic Topic template.) When you go to insert a conref in your target file, you won’t have to hunt for the source. You will know exactly where to find it. 

Now, each time developers change a name, you simply make the change in one, easy-to-find file.