In my previous post (Big Rewards for a Short Description), I talked about the importance of the short description <shortdesc> element. Effective short descriptions are an opportunity to help users easily find the correct information for which they are looking. Keep the following best practices in mind when writing your short descriptions.
Do not use cross-references within the <shortdesc> element
“Wait a minute,” you say. “I tried to do that, and DITA won’t allow it.” Yes, that’s true. But, there is a fairly simple hack that allows you to include a cross-reference. Why shouldn’t you use the hack? Let’s go back to the intended use of the <shortdesc> element. To quote the DITA 1.2 Specification, “The short description, which represents the purpose or theme of the topic, is also intended to be used as a link preview and for searching.” In other words, the short description is a synopsis of the topic. Using a cross-reference to another topic makes no sense. Put the cross-reference somewhere in the text of the topic or in a related topics section.
Consistently use a <shortdesc> element
The <shortdesc> element isn’t mandatory. If you want a quality document, however, you should make it mandatory. See my previous post on the rewards you can get from using short descriptions. If you have topics nested in your main topic, those topic titles are are automatically generated as links at the end of the main topic. (In DITA, the main topic is listed as the parent topic and the nested topics are the child topics.) Under the topic title is the text in the <shortdesc> element. If you use short descriptions in some topics and not in others, the previews for child topic links will appear incongruous. And your readers could lose confidence in your document.
