May PDX DITA Book Club recap: Short Descriptions

We discussed Chapter 5: Short Descriptions of DITA Best Practices at the May 18th meeting of the PDX DITA Book Club. Attendees included DITA enthusiasts from Jive Software, NetApp, Daimler, and PSU’s Technical Writing program.

book club

Personally, my favorite thing about short descriptions is the way they show up in mini-TOCs. I love being able to easily view a summary of the information in a set of topics. It helps me organize my information, and it helps readers know what to expect, too.

While it seems like there isn’t much we could add to the illuminating and in-depth presentation and blog post that Marya DeVoto did on short descriptions, here are some highlights from the meeting!

  • A helpful short description could make it so that an advanced user wouldn’t even have to read the topic.
  • To a similar point, sometimes the short description IS the whole topic, and that’s okay.
  • Short descriptions should be readable on their own. Avoid introducing lists in a short description, and refer to other topics by name instead of by “previous topic” or “next topic.”
  • Being consistent in applying short descriptions helps search results.

Some great final advice from Marya–if your topics are well-structured, your short descriptions should be easy to write. If you are having difficulty writing it, take a second look at your topic and make sure it contains only one point or task.

Couldn’t make it to the meeting but have something to add? What’s your favorite thing about short descriptions? Discuss in the comments!

More people are coming to every meeting! You should join us for the next PDX DITA Book Club meeting:
Where: Jive Software, 915 SW Stark Street, Portland, OR
When: June 22, 2016 from 5:00 to 6:00 pm
What: Chapter 8 and 9 of DITA Best Practices
RSVP: Email

shortdesc: an exploration

At the June meetup of PDX DITA I presented a brief talk about the <shortdesc> element, which had been puzzling me for a long time. Due to tragic audio failure, several remote attendees couldn’t tune in, so I promised a blog rendition of the talk. The post below is not a strict transcription, but it attempts to capture most of the main points, including some that emerged during the Q&A.


[meets] deep but possibly unacknowledged needs

–Don Day,

 perhaps the most versatile and yet most challenging element to write for

–Laura Bellamy, Michelle Carey, and Jenifer Schlotfeldt,
DITA Best Practices

As the quotations above suggest, the humble <shortdesc> element has inspired a surprising amount of passion in writers about DITA. Pretty grandiose for a piece of text that’s often ignored and when it isn’t, takes up at most a couple of sentences per topic. Why is the shortdesc such an object of mystery?

I’m not sure I have an answer, so let’s start with a few non-mysterious facts.

What is <shortdesc>?

The shortdesc:

  • Is an optional element that precedes the topic body in a topic
  • Provides clues about topic content (enabling the “progressive disclosure model”–readers can scan it to see if they want to read on)
  • Shows up in search results and link previews as well as the body of the topic
Here are a few things the shortdesc isn’t (or shouldn’t be):
  • A  lead-in or introduction
  • A promise about the contents of the topic
  • A sentence fragment

Why use <shortdesc>?

None of these facts really gets at what the shortdesc is for.  Here is the OASIS reference’s summation of the purpose, which goes a little farther in explaining where the shortdesc shows up, but doesn’t quite get to the heart of things.

The short description, which represents the purpose or theme of the topic, is also intended to be used as a link preview and for searching. When used within a DITA map, the short description of the <topicref> can be used to override the short description in the topic.

What is implied here, but not quite said, is that the shortdesc should answer the “so what”? question–in other words, what is the value in this topic, and why should I care about it? The shortdesc should either try and deflect the need to actually read the topic, by extracting the key and most actionable piece of information (especially effective with tasks), or it should attempt to help a reader decide whether this topic will actually be useful enough to be worth reading. The best case is that you can mouse over a shortdesc or find it in a mini-TOC and actually find the key detail you need without reading further–and there are topics that might well consist entirely of the shortdesc. (Imagine a topic of which the shortdesc is “You should install Service Pack 3 before attempting to install the latest version; otherwise your installation will fail.”) But the second best case is that you can tell whether or not this is the topic YOU need to read. For example, a shortdesc to a longer topic with several paragraphs might specify use case information about where the information is applicable. For example, a shortdesc that says “Users who need to use this technology in a distributed environment should understand the flow of information between servers.” You can achieve some of these goals by writing clear titles–but shortdescs give you a lot more space.

Because the content of shortdesc is promoted in search and shows up in a number of places as described below, making the shortdesc valuable in itself or a clear indicator of where to find value is very useful.

Where Does <shortdesc> Show Up?

<shortdesc> shows up helpfully in many places:
  • At the top of the topic in output
  • When you mouse over a cross-ref to the topic in HTML
  • In a mini-toc inside a top-level topic with several topics nested underneath it
  • In search results (internal to a Help system, or in a search engine)

The Need for Consistency

This multi-usefulness, however, creates consistency problems. If you don’t use a shortdesc in EVERY topic, you’ll see mini-TOCs in your output with gaps in them. If some of your short descriptions are sentence fragments, or if some are very long and some are very short, or if they use very different sentence structure, you can find yourself inadvertently creating TOCs with faulty parallelism. This isn’t the end of the world in terms of usability, but it looks sloppy and will annoy people who should be paying attention to your fantastic content.


Some Technical Limitations

<shortdesc> can’t contain any of the following items, so you can’t get too fancy with them. It’s best to think of them as a text-only element since they can’t have:
  • Conditional formatting (use <abstract> if you need to do this)
  • x-refs
  • codeblocks, lists, tables, or other fancy formatting

Challenges of <shortdesc>, Summarized

<shortdesc> is going to work best if your DITA implementation is already working well. If your content isn’t well-structured and concise with a clear purpose for each topic (concept, task, and reference) and a modular structure, it will be hard to write a clear shortdesc–in fact, difficulty in writing a shortdesc may be an early warning about content problems. If your team isn’t working with a clear idea of how to write a shortdesc, you’ll end up with consistency problems, so you need to communicate about what you’re doing. And if you have a lot of legacy content, you may find yourself writing this element in bulk which is probably not most people’s idea of fun.

Most of all, the <shortdesc> element needs to function in multiple contexts and be used consistently. Otherwise you’ll end up with confusing search results or hover text, and mini-TOCs that are gappy or not especially helpful. As we learned in our meetup this June, some people just decide not to deal with this tricky element.

Tips for Success

Nevertheless, <shortdesc> can have a lot of utility in highlighting valuable content. Here are some tips to make yours effective.

  • Use complete sentences.
  • Make sure your content can either stand alone (in which case consider formatting it distinctively in the output) or that it works as the opening of the topic.
  • Don’t be long-winded.
  • Use a consistent sentence structure. Statements work best.
  • Try and offer a takeaway that relieves someone from reading.
  • Don’t promise (e.g. “the following methods work:)
  • Be systematic in getting them done.
  • If a topic contains only one sentence, just make it the shortdesc.
  • If you have them, make shortdescs for “container topics” cover the nested topics succinctly.

How About You?

In our meetup, we learned that most people in our group are using <shortdesc> fairly traditionally, as described above, or else not using it at all. However, we keep hearing rumors about creative uses including special formatting and tool tips. If you have some ingenious ideas about how to use them, we’d love to hear from you in comments or at our next meetup.