ShortdescThe 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. When used within a DITA map,
the short description of the <topicref> can be used to override the short
description in the topic.
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 instead 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 conceptual 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.
|
[edit] Contains
[edit] Contained by
| Doctype
| Parents
|
| bookmap
| topicmeta, bookmeta
|
| map
| topicmeta
|
| ditabase
| topic, abstract, concept, task, reference, glossdef
|
| topic
| topic, abstract
|
| task
| topic, abstract, task
|
| concept
| topic, abstract, concept
|
| reference
| topic, abstract, reference
|
| glossary
| topic, abstract, concept, glossdef
|
[edit] Inheritance:
"- topic/shortdesc " when used in topics, and "- map/shortdesc " when used in maps.
[edit] Attributes
| Name
| Description
| Data Type
| Default Value
| Required?
|
| %univ-atts; (%select-atts;, %id-atts;, %localization-atts;)
| A set of related attributes, described at %univ-atts;
| parameter entity
| PE not
applicable
| Not applicable
|
| %global-atts; (xtrf, xtrc)
| A set of related attributes, described at %global-atts;
| parameter entity
| PE not
applicable
| Not applicable
|
| class, outputclass
| Common attributes described in Other common DITA attributes
|
|
|
|
TOC: Language Specification 1.1
Parent topic: Topic elements
Previous topic: abstract
Next topic: body
|
|
