shortdesc
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 Do not use sentence fragments.
Use complete sentences. Avoid starting short descriptions with phrases such
as |
| 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 |
| 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. |
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
Contains
Note
| Doctype | Content model |
|---|---|
| topic (base), map (base), classifyMap, subjectScheme, learningAssessment, learningBookmap, learningContent, learningMap, 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) |
| topic (technical content), map (technical content), concept, ditabase, glossary, glossentry, glossgroup, reference, task, bookmap | ( 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
- The shortdesc must be directly contained by the abstract.
Example: abstract with multiple short descriptions
<abstract>The abstract is being used to provide more complex content. <shortdesc>The shortdesc must be directly contained by the abstract.</shortdesc> <p>The abstract can put text around the shortdesc.</p> <shortdesc>There can be more than one shortdesc.</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.
There can be more than one shortdesc.
- Preview/summary output
- The shortdesc must be directly contained by the abstract. There can be more than one shortdesc.
Attributes
| Name | Description | Data Type | Default Value | Required? |
|---|---|---|---|---|
| univ-atts attribute group (includes select-atts, id-atts, and localization-atts groups) | A set of related attributes, described in univ-atts attribute group | |||
| global-atts attribute group (xtrf, xtrc) | A set of related attributes, described in global-atts attribute group | |||
| class, outputclass | Common attributes described in Other common DITA attributes |