The shortdesc element

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

2 thoughts on “The shortdesc element

  1. Ray Gallon says:

    Hi Don,

    I totally agree. I’ve been using DITA generic topics to produce riche tool tips. The shortdesc is what pops up on hover. Click on the shortdesc, and you get a slider with a paragraph more of information (still real short) and a link to a full task or concept.

    We developed the concept first, then looked for the DITA components to implement it. It was, in fact, a no-brainer. Shortdesc is, indeed, one of the handiest tools around, and it’s so easy to use!

Leave a Reply

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