[Guest Post] “Reflections on Writing Short Descriptions”, by Tony Self
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
Example of Short Descriptions drafted withthe “This Topic “approach
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.
https://blogsimages.adobe.com/techcomm/files/2013/06/example_shortdesc_good.png
Example of Short Descriptions drafted with the “thesis statement”approach
Thesis statements, applied to each topic in a modular, topic-based document, serve to:
- advise the reader of the significance and relevance of the topic
- help the reader decide whether to continue reading the topic
- help the skimming reader understand the central theme of the topic without reading the remainder of the content
- answers
- the reader’s questions of “what” and “why”.
Advantages of a distinct style
I also modified the processing of my own topics so that the short descriptions in the topic were more easily recognizable. Rather than appearing in the same style as normal paragraphs in the output, I used a distinctive styling which distinguished the shortdesc metadata from the content.
https://blogsimages.adobe.com/techcomm/files/2013/06/example_shortdesc_recognition.png
Example of distinctive styling applied toshort descriptions in topics
I wish I could have made this blog post shorter, but like Pascal, I did not have the time!
Previous post by Dr. Tony Self: