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.

Short descriptions serve multiple purposes within a document. This is one of the reasons that it is difficult to categorise shortdesc as content (data) or metadata. Technically, shortdesc is metadata because it falls outside the topic body element.

To complicate matters further, DITA includes a semantically similar element, the abstract, which serves a similar function (and can act as an alternative) to shortdesc.

Writing short descriptions induces the writer to clarify the main thesis of the topic. If you cannot write a short description of within the recommended 50 word limit, the topic is probably too complex and needs to be divided. If the short description doesn't add any meaning to the topic, then the topic may not contain a coherent idea.

A concise and complete short description should be written for every DITA topic.