How would you complete this simile? A topic needs a shortdesc like:

1. A conference-goer needed her business cards.
2. A man needs to ask for directions.
3. A link needs a hover tip to explain what it leads to.
4. A fish needs a bicycle.

I included item #4 because some writing teams are ambivalent about the shortdesc element and have adopted guidelines to skip its use. If you are in that camp, I just want to say this: of all the DITA elements, shortdesc is most like a credit card with a loyalty program that rewards you for using it. That’s because whenever you include a shortdesc in a topic, any link that points to that topic from anywhere in the build map will have that short description as its title attribute content, popping up some progressively more revealing bit of information about the topic before the reader finally clicks on it to get the full story. And that is what items 1, 2, and 3 are about: the deep but possibly unacknowledged needs that sometimes keep the rest of the story from happening.

Did you know?

The DITA 1.2 Language Reference’s article about the shortdesc element includes a helpful set of guides for how to write a short description that is appropriate for each of the major topic types in DITA. If you are just getting started in DITA or if your usage doesn’t need to be quite so fancy at this stage, it’s okay to think of the short description as a special first paragraph, much like the intro paragraph of a classic essay (tell them what you’re going to tell them). Your links will love you for it.

If you need richer content for the opening to your topic, check out the abstract element.

Deep Dive

• DITA 1.2 Spec: shortdesc
• Irina Dunn, originator of “like a fish needs a bicycle.”