Home
Syntax and mark-up
Short descriptions
The short description (or shortdesc) is arguably the most important component of a DITA topic, and is also one of the most difficult elements to write. Short descriptions should be written for every topic.
Cross-references and typography in shortdesc elements
Although it is possible to embed a phrase (ph) element in a shortdesc, and then include formatting and xref elements within the phrase, it is not a semantically sound practice.

Introduction
Information types and topics
Topics are the building blocks of modular documents, and organising topics by semantic information types is one of the architectural features of DITA.
DITA map files
Syntax and mark-up
- Organisation of DITA elements
  Elements in DITA are grouped together into a number of categories for organisational and comprehension purposes.
- Working with mark-up
- Element domains
  Elements in DITA are arranged into domains for organisational purposes and technical reasons.
- Short descriptions
  The short description (or shortdesc) is arguably the most important component of a DITA topic, and is also one of the most difficult elements to write. Short descriptions should be written for every topic.
  - Purpose of short descriptions
    Short descriptions typically perform three different functions: providing an overview in the first paragraph of the topic, as link preview text (or hover text) in hypertext outputs, and as part of the subordinate topic preview text in the parent of the topic.
  - Guidelines for crafting short descriptions
    Short descriptions are difficult and time consuming to write. Following guidelines for shortdesc creation will make the task easier, and result in more consistent descriptions.
  - Abstracts
    Abstracts can contain multiple shortdesc elements, which are typically processed slightly differently to standalone shortdesc elements.
  - Cross-references and typography in shortdesc elements
    Although it is possible to embed a phrase (ph) element in a shortdesc, and then include formatting and xref elements within the phrase, it is not a semantically sound practice.
  - Making shortdesc elements compulsory
    It is possible for publishing teams to make the use of short descriptions mandatory through specialisation and constraints mechanisms within DITA.
  - Short descriptions in the ditamap
    Short descriptions specified in a DITA topic can be overridden by alternative short description elements in the ditamap.
- Lists
  The purpose of a list is to make it easier for the reader to understand sequences of information and collections of like information. Different types of lists are used for different information structures.
- Paragraphs
  Paragraphs are the basic components of topics. A paragraph (p) element should be a self-contained unit dealing with one idea or point, typically expressed in two or more related sentences. The p element should be used when no other semantically-specific block element is available.
- Procedures and steps
  The purpose of procedural documents is to explain to the reader how to accomplish tasks. The task information type is specifically designed for procedures, with a well-defined structure built around steps.
- Tables
  The purpose of a table is to structure, organise and present factual data that a user will need to look up or reference. There are two general purpose table types in DITA: table and simpletable.
- Phrases
  The semantics of words and phrases in DITA content is expressed through a broad range of phrase elements.
- Special characters and dates
Language and punctuation
Graphics and figures
Cross-referencing
Cross-references are a means of binding individual topics into a coherent and navigable document.
Content re-use
Metadata, conditional processing, and indexing
The DITA documentation process
DITA authoring concepts
Moving from style-based authoring to a structured authoring methodology such as DITA requires a radically different approach to writing.

Cross-references and typography in shortdesc elements

Although it is possible to embed a phrase (ph) element in a shortdesc, and then include formatting and xref elements within the phrase, it is not a semantically sound practice.

At first glance, the shortdesc element seems unable to contain some inline mark-up such as cross-references. On closer examination, it becomes apparent that a ph inline element can be inserted, and that ph element can contain cross-references.

Although the DITA language technically permits this sort of mark-up construct, hacks such as this should not be used.

Example of invalid code:

<shortdesc>The <xref href="c_turbo.dita#c4753/turbo_overview">
turbocharger systems</xref> uses...

Example of technically valid, but unwise, code:

<shortdesc>The <ph><xref href="c_turbo.dita#c4753/turbo_overview">
turbocharger systems</xref></ph> uses...

The shortdesc element is intended to contain a brief synopsis of the content of the topic, and isn't necessarily intended to be output as part of the topic content. It is intended for link previews and hover text; it doesn't make sense to include cross-references in these.

In the same way, typographical elements such as bold (b) and italic (i) are not usually appropriate in short descriptions, even though they are technically valid, because short descriptions are often rendered in plain text forms (such as in tooltips). If you think you need such formatting, you should consider whether the content you are including really belongs in a shortdesc element.

The shortdesc should be treated as metadata, not content.

A shortdesc may legitimately need some inline mark-up, such as where a superscript or subscript character is needed. For example, a shortdec might discuss water as H<sub>2</sub>O. This will inevitably present a problem when the shortdesc text is used in a context where subscripts are not permitted, such as in a tooltip or an HTML topic title.

Inline mark-up in a shortdesc should therefore be avoided where the formatting of that mark-up in the output is important to its meaning.