shortdesc

Darwin Information Typing Architecture (DITA) Version 1.3 Part 2: Technical Content Edition

version
1.3
author
OASIS DITA Technical Committee

The shortdesc element provides a short description of the topic. The short description, which represents the purpose or theme of the topic, is also intended to be used as a link preview and for search results. The element can occur both in topics and maps.

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

Short descriptions in topics

The content of the shortdesc element SHOULD be rendered as the initial paragraph of 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 to provide richer content around the shortdesc. See the abstract description for more information about the behavior of shortdesc in an abstract.

While the shortdesc element is optional, it is recommended that topics contain this element. When a topic contains only one paragraph, it is preferable to include the text in the shortdesc and omit the topic body or leave it empty.

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.

Short descriptions in maps

The shortdesc element can be used in DITA maps and associated with topicref elements. This enables map authors to accomplish the following goals:

  • Associate a short description with a non-DITA object.
  • Provide a short description that is specific to the map context and used for link previews.
  • Override the short description located in the associated DITA topic, when the copy-to attribute is specified. Processors might not implement this behavior.

When processors generate link previews that are based on the map context, they SHOULD use the content of the shortdesc that is located in the map rather than the shortdesc that is located in the DITA topic. However, processors SHOULD use the content of the shortdesc element in the DITA topic when they render the topic itself, unless the copy-to attribute is specified on the topic reference to the element.

When a shortdesc element applies to an entire DITA map, it serves as description only.

Content models

See appendix for information about this element in OASIS document type shells.

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

The following attributes are available on this element: Universal attribute group and outputclass.