Short description

A short description is text that briefly introduces and describes a topic. In DITA, short desciptions are tagged with the short description element (<shortdesc>).

Example

<concept id="debuggingtools_overview">
<title>About the debugging, reporting, 
and file generation tools</title>

<shortdesc>Information about tools and techniques 
you can use to debug your processing problems, 
get information about your source files, 
and generate DITA files automatically from XML-based source code.</shortdesc>

				

The DITA short description is one device to achieve "progressive disclosure" in topic-based writing, in the sense that title expands to short description, which expands to the topic itself as a user drills into information. Consistent use of short description helps to provide this progressive user experience. The "short description" approach in writing topics could be compared with the "topic sentence" approach in writing paragraphs that is regularly taught in classes from elementary school through college.

The DITA short description has several functions (and reiterating the title is not one of them):

• To act as a sort of "thesis paragraph" for the topic, letting readers quickly assess whether it's worth continuing
• To act as a link hover help in related topics, letting uncertain readers get a sense of the target's content when the title isn't enough
• To act as a summary of the content in generated overviews, letting readers who are drilling down from higher-level content navigate successfully to the right answer through progressive disclosure instead of massive scanning