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.
Have you got any best practices that your team follows? Please share if you do.
