Reflections on Writing Short Descriptions

Tuesday, June 18 2013 @ 5:21 PM, By Maxwell Hoffmann

Guest blogger, thought leader Tony Self, has written a second installment in a 2-part series of thought provoking blogs on relevant trends. You will find a link to his previous blog at the end of this article.

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 blog by Dr. Tony Self

About our guest blogger:

Based in Melbourne, Australia, Dr Tony Self (@hyperwrite) 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 mark-up 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.

COMMENTS

  • By Marie-L. Flacke - 11:34 AM on June 30, 2013  

    Excellent!

  • By Baru Winardi - 10:59 AM on March 12, 2014  

    Hi, this weekend is fastidious designed for me, because this point in time i am reading this wonderful logo designers

  • Categories

  • Archives

  • Authors

  • Useful Links

  • Recent Comments

    • Joel: Thanks for fixing the links guys!
    • Maxwell Hoffmann: Ted, one aspect of the blog that may have escaped your notice; you can launch the HTML5 version in...
    • Maxwell Hoffmann: Joel, per comments made above, I discovered that the original URLs were incorrect with pointers to...
    • Maxwell Hoffmann: Paul, as I indicated in the comments below, the original blog had links that pointed to a...
    • Maxwell Hoffmann: I apologize to all concerned regarding my suggestion to “clear the cache” … it...