shortdesc

The short description (<shortdesc>) element occurs between the topic title and the topic body, as the initial paragraph-like content of a topic, or it can be embedded in an abstract element. 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. The <shortdesc> element also can be used in a DITA map.

Use the <shortdesc> element when the first paragraph of topic content is simple enough to be suitable for use as a link preview or for summaries. Otherwise use the <abstract> element to provide richer content around the <shortdesc>. See the abstract description for more details on the behavior of <shortdesc> in an abstract.

While inclusion of the <shortdesc> element is not mandated by DITA or the tools, it is recommended that topics contain this element. In cases where a topic contains only one paragraph, then it is preferable to include this text in the <shortdesc> and leave the topic body empty.

The short description should be a single, concise paragraph containing one or two sentences of no more than 50 words.

Type	Recommended content
Task	The short description should explain what the task information helps users accomplish, the benefits of the task, or the purpose of the task. Do not simply repeat the title. Try to include information that will help users understand when the task is appropriate or why the task is necessary. Avoid stating the obvious, such as "You can use XYZ to do A" as the only statement in the short description for Task A. In some cases, add more information about why the task is beneficial. Do not use sentence fragments. Use complete sentences. Avoid starting short descriptions with phrases such as "This topic describes . . . ." or "This topic is about . . . ."
Concept	Introduce the concept and provide a concise answer to the question "What is this?" and in some cases "Why do I care about this?" If the concept is unfamiliar, you can start with a brief definition. Avoid using the short description to lead in or build up to a topic. The short description paragraph should contain the main point of the concept topic. The concept short description should clearly apply to a concept. Avoid turning the concept topic into a task. Do not simply repeat the title. Do not use sentence fragments. Use complete sentences. Avoid starting short descriptions with phrases such as "This topic describes . . . ." or "This topic is about . . . ."
Reference	Briefly describe what the reference item does, what it is, or what it is used for. In most cases, use a complete sentence. You can use a sentence fragment only for a topic that is very short, such as an API topic and each of its subtopics. Use consistent phrasing across libraries and information centers so that your information can be seamlessly integrated with another product's information.

Type

Short descriptions in maps

The <shortdesc> element is also available in maps within the <topicmeta> element. In a map, the element specifies that a topic has a short description that is specific to the context of that topicref in that map. When constructing link previews, links that are generated according to the context of the map should use the <shortdesc> content provided in the map rather than the <shortdesc> provided in the topic. The <shortdesc> element in the map allows authors to provide short descriptions for references to non-DITA objects.

The content of the <shortdesc> element also can be used to override the short description of the topic, when the copy-to attribute is specified.

Note: Processors may or may not implement this behavior.

Contains

Note: These models represent only the default document types distributed by OASIS. Actual content models will differ with each new document type.

Doctype	Content model
topic (base), learningAssessment, learningContent, learningOverview, learningPlan, learningSummary	( text data or boolean or keyword or ph or b or i or sup or sub or tt or u or q or term or tm or state or data or data-about or foreign or unknown or image or draft-comment) (any number)
map, bookmap, classifyMap, subjectScheme, learningBookmap, learningMap	( text data or boolean or keyword or ph or q or term or tm or state or data or data-about or foreign or unknown or image or draft-comment) (any number)
topic (technical content), concept, ditabase, glossary, glossentry, glossgroup, reference, task	( text data or boolean or keyword or apiname or option or parmname or cmdname or msgnum or varname or wintitle or ph or b or i or sup or sub or tt or u or codeph or synph or filepath or msgph or systemoutput or userinput or menucascade or uicontrol or q or term or abbreviated-form or tm or state or data or data-about or foreign or unknown or image or draft-comment) (any number)
machineryTask	( text data or boolean or keyword or wintitle or ph or b or i or sup or sub or tt or u or menucascade or uicontrol or q or term or tm or state or data or data-about or foreign or unknown or image or draft-comment) (any number)

Contained by

Doctype	Content model
topic (base), topic (technical content)	topic, abstract
map (base), map (technical content), classifyMap, learningMap	topicmeta
concept	topic, abstract, concept
ditabase	topic, abstract, concept, task, reference, glossdef
glossary, glossentry, glossgroup	topic, abstract, concept, glossdef
reference	topic, abstract, reference
task (strict), task (general), machineryTask	topic, abstract, task
bookmap, learningBookmap	topicmeta, bookmeta
subjectScheme	topicmeta, subjectHeadMeta
learningAssessment	topic, abstract, learningBase, learningAssessment
learningContent	topic, abstract, learningBase, task, concept, reference, learningSummary, learningAssessment, learningContent
learningOverview	topic, abstract, learningBase, learningOverview
learningPlan	topic, abstract, learningBase, learningPlan
learningSummary	topic, abstract, learningBase, learningSummary

Inheritance

"- topic/shortdesc " when used in topics, and "- map/shortdesc " when used in maps.

Examples

The following example demonstrates the use of a stand-alone shortdesc inside of a concept topic.

<concept id="concept">
 <title>Introduction to Bird Calling</title>
 <shortdesc>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.</shortdesc>
 <conbody>
   <p>Bird calling requires learning:</p>
   <ul>
    <li>Popular and classical bird songs</li>
    <li>How to whistle like a bird</li>
   </ul>
 </conbody>
</concept>

Example: short description within a map

<topicref href="myThing.dita">
  <topicmeta>
    <navtitle>Navigation title for my topic</navtitle>
    <shortdesc>A description of myThing that is specific to this context.</shortdesc>
  </topicmeta>
</topicref>
<topicref href="http://www.example.org" scope="external">
  <topicmeta>
    <navtitle>Example website</navtitle>
    <shortdesc>The example.org address is often used in examples</shortdesc>
  </topicmeta>
</topicref>

Example: abstract with phrase-level short description

<abstract>The abstract is being used to provide more complex content. 
	<shortdesc>The shortdesc must be directly contained by the abstract.</shortdesc>
The abstract can put text around the shortdesc.
</abstract>

Topic output: The abstract is being used to provide more complex content. The shortdesc must be directly contained by the abstract. The abstract can put text around the shortdesc.
Preview/summary output: The shortdesc must be directly contained by the abstract.

Example: abstract with block-level short description

<abstract><p>The abstract is being used to provide more complex content.</p> 
	<shortdesc>The shortdesc must be directly contained by the abstract.</shortdesc>
<p>The abstract can put text around the shortdesc.</p>
</abstract>

Topic output

The abstract is being used to provide more complex content.

The shortdesc must be directly contained by the abstract.

The abstract can put text around the shortdesc.

Preview/summary output