[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 with
the “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:

  • 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.

Example of distinctive styling applied to short descriptions in topics
Example of distinctive styling applied to
short 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:

Tony Self

Tony Self

Dr. Tony Self is based in Melbourne, Australia. He has over 30 years of experience as a technical communicator. For over 20 years, Tony has worked in the areas of online help systems, computer-based training, and XML documents. In 1993, he founded HyperWrite, a company providing training and consultancy in structured authoring, Help systems, DITA, and technology strategy. Tony completed his PhD in semantic markup languages in 2011, and his book “The DITA Style Guide” was published in the same year. He is a member of the OASIS DITA Technical Committee (and chair of the DITA Help Subcommittee), is an adjunct teaching fellow at Swinburne University, and is the Director of Training for TCTrainNet, a training initiative of tekom, the German professional association for technical communicators.

4 thoughts to “[Guest Post] “Reflections on Writing Short Descriptions”, by Tony Self”

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.