[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!

Example of Short Descriptions drafted with the "This Topic "approach

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.

Example of Short Descriptions drafted with the "thesis statement"approach

Example of Short Descriptions drafted with the “thesis statement”approach

Thesis statements, applied to each topic in a modular, topic-based document, serve to:

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.

Example of distinctive styling applied to short descriptions in topics

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: