Tools for reuse--The conref attribute

The conref attribute (conref stands for content reference) allows you to reuse text at an element level.

Suppose you want to reuse the text of a warning. You would assign an element ID to the note tag containing the warning text in the original file. In a second file, you would reference that warning  by using the conref attribute on a note tag.

 For example, the original file is named topic1.dita with a topic ID of 111. The note tag reads:

 <note id="damage" type="warning"> You can cause serious damage.</note>

Notice that the element ID on the note tag is damage. 

Here’s the syntax you would use for the conref attribute:

filename.xml#topicid/elementid

The note tag in the second file would read:

 <note conref="topic.dita#111/damage"/> 
 
The result would be a duplicate of the original warning.

In my next posting, I will discuss a best practice for conrefs.

Single-sourcing and reuse

A big benefit of DITA is single-sourcing.

If you publish to multiple formats (web, online help, print, and so on), you can use the same set of DITA files for each piece of content. And that means that one set of files for multiple formats can be stored in one repository. You don't have to worry about making the same updates in multiple file sets. Single-sourcing  strengthens the way you create, develop and maintain content.

Single-sourcing also allows for another key feature of DITA--reuse. With DITA, you can reuse documentation that was created for one document in another document. For example, you could use a topic in training courseware, in a user guide, and in marketing information.

 You can reuse a whole topic or part of a topic.

To reuse a topic, you would simply include the same topicref in a new ditamap. To reuse a part of a topic, you would assign an ID to the portion you want to reuse, and then use a conref attribute in the new topic to incorporate that portion.

This allows for consistent use of terminology, instructions, and concepts. And what happens when you have consistent information? Your customer gains confidence in your documentation and your product.

Before you begin

One of the most common mistakes organizations make when converting to DITA is to not properly train their writers. I’m not talking about DITA training. The training that is missed is the reason for DITA—that is, topic-based authoring. Writers that are well-trained in topic-based authoring will appreciate the benefits of DITA.

Topic-based documentation is tailor-made for users who don’t have a lot of time to read. Topic-based documentation gets to the point. Each topic answers one question: 

"How do I ..." 

"What is ...?" 

"What went wrong?"  

Topics should only be a few paragraphs long and stick to one subject. So, not only are topics easier to read, they should be easier to review. Subject Matter Experts who are reviewing the documentation will appreciate being able to quickly find and review information. And what tech writer wouldn't appreciate a cooperative (or dare I say, enthusiastic) reviewer?

One of the best examples I’ve seen regarding topic-based authoring is the example given in the article Topography, Muffins, and Chunking. Check it out and let me know if you agree.

Note: Thanks to Michael McGrail for helping me get started with this blog. For tips on increasing your productivity, check out his blog The Productivity Source.