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. 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.

Contains

Doctype Content model
ditabase, topic, task, reference, concept ( text data or ph or codeph or synph or filepath or msgph or userinput or systemoutput or b or u or i or tt or sup or sub or uicontrol or menucascade or term or q or boolean or state or keyword or option or parmname or apiname or cmdname or msgnum or varname or wintitle or tm or image or data or data-about or foreign or unknown) (any number)
map, bookmap ( text data or ph or term or q or boolean or state or keyword or tm or image or data or data-about or foreign or unknown) (any number)

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

Inheritance:

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

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      

Return to main page.

OASIS DITA Language Specification v1.1 -- Committee Draft 02, 8 May 2007
Copyright © OASIS Open 2005, 2007. All Rights Reserved.