The <shortdesc> element is usually one sentence. Sometimes two or more. But your editors will tell you to keep it short. Its name is what it is supposed to be. That is, a short description of the topic it is introducing.
The <shortdesc> element is common to all DITA types of topics: Concept, Task, and Reference. It is the first paragraph in a topic. However, it isn’t mandatory. You can eliminate the element and you will still have a valid DITA document.
So why use it?
A colleague of mine, Don Day, wrote “… of all the DITA elements, shortdesc is most like a credit card with a loyalty program that rewards you for using it.”
What kind of rewards does the <shortdesc> element provide? Very simply, it allows readers to easily find the correct information for which they are looking.
Easy to find
In Developing Quality Technical Information: A Handbook for Writers and Editors, the authors identify nine characteristics that quality information shares.
These characteristics are further grouped under:
- Easy to use
- Easy to understand
- Easy to find
If a reader can’t find information they need to use product, they can become frustrated. And most likely, frustrated readers become disenchanted users. And that leads to bad product reviews. To avoid that road, take some time with your <shortdesc> element.
The first paragraph
Since it is the first paragraph in a topic, a well-written short description will tell the reader if it contains the information for which they are looking. A well written short description will contain keywords that will help the reader identify whether the topic contains useful information. It should be a concise description of the topic.
Here’s an example of a bad short description for a topic called “Introduction to Bird Calling” in documentation for the Acme Bird Feeder. The following topic contains instructions on how to master bird calling. After reading the topic, the reader thinks “Why should I care about bird calling? All I want to do is feed the birds.” When the short description is rewritten, the reader is given more information.If you wish to attract more birds to your Acme Bird Feeder, learn the art of bird calling. Bird calling is an efficient way to alert more birds to the presence of your bird feeder. “Ah,” says the reader. “This topic will ensure that that I alert the birds that dinner is served! I’m getting the most bang for the bucks I put out for this bird feeder. The Acme Corporation has earned my loyalty!”
Preview for links in online documents
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. A link to the parent topic is also automatically generated at the end of the child topic. The short description, however, is not listed under the link. But, you can hover your cursor over the link and the short description is displayed. (This is also the case for Related Information links.)
Search engine results for online documents
Short descriptions appear in search engine results. So, well written short descriptions lets the searcher know that the information required is in your document. If you put key terms in your short description, your ranking in search results will be improved. That is, your document will show up in the search results before other documents.
Summary
Effective short descriptions are an opportunity to help users easily find the correct information for which they are looking. Satisfied documentation users lead to satisfied product users. Satisfied product users lead to good product reviews. Good product reviews lead to good sales numbers.
