A major challenge in DITA
One of the most difficult tasks when working in DITA is writing short descriptions or abstracts.
French philosopher Blaise Pascal is credited with the line, “I would have written a shorter letter, but I did not have the time”, and every writer recognizes the truth in that statement.
In DITA, the short description is not a mandatory element, but there are strong arguments for considering it so. In my book, The DITA Style Guide, the short description for the Short descriptions topic makes such a recommendation. “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.”
There is an art to writing short descriptions, or crafting them, as is probably a better way of putting it. The best approach seems to treat the short description as a “thesis statement”, which leads to more effective, expository descriptions.
An early approach to short descriptions
When I started writing DITA topics, my approach to short descriptions was to write a one sentence expansion of the topic heading, start with “This topic …”. I believed at the time that this approach delivered a useful introductory paragraph for the topic.
When I started to view the short description as metadata, rather than content, my views changed. When the shortdesc is used as progressive disclosure devices, particularly in stub topics, it became obvious that the “this topic” form was clumsy, and did not result in expository preview text. Such “this topic” short descriptions often presented redundant information, repeating the information in the topic heading albeit with different wording. I needed to spend more time on the short description, in direct proportion to their importance. If readers have the patience to read less and less information, short descriptions may be the only part of a topic they read!
https://blogsimages.adobe.com/techcomm/files/2013/06/example_shortdesc_poor.png
The thesis approach
After attending a presentation by Kris Eberlein on crafting short descriptions at the 2008 DITA Europe Conference, reviewing the slides from the Short Description Guidelines presentation by Michelle Carey and Shannon Rouiller to the Silicon Valley DITA Interest Group, and researching the STOP methodology, I concluded that the thesis statement approach was preferable.
This change has resulted in better quality summaries that work effectively as overview paragraphs in a topic, and as progressive disclosure devices. The focus is now more on the information than on the topic unit.
