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.

This table is a summary of the recommendations made by Kris Eberlein in her Art of the Short Description presentation at the 2007 DITA Europe Conference.
Do: Don't
  • Make the shortdesc standalone, so that the topic is not dependent upon the shortdesc.
  • Make the shortdesc concise and complete.
  • Include less than 50 words in only one or two sentences.
  • Use complete sentences, except for short topics such as in API documentation.
  • Restate the title.
  • State the obvious.
  • Start the shortdesc with "this topic...".
  • Use the shortdesc as a lead-in sentence.

Different approaches to writing short descriptions are required for different information types.

Information Type Guidelines
Task

The shortdesc should answer the questions of what are the benefits of the task, and what is the purpose of the task. Include information about when the user should perform the task (or why the task is necessary). If applicable, include information about who performs the task.

Concept

The shortdesc should answer the questions of what is this, and why do I care about this. Start with a brief definition, if the concept is unfamiliar. Make sure the shortdesc contains the main point of the topic.

Reference

The shortdesc should answer the questions of what are the items, what do they do, and what are they used for. Use consistent phrasing across document sets so that your information can be easily integrated into a range of publications.