Do you recall what critter is known as “a horse designed by a committee?” That’s right, the abstract element!
The 2005-era OASIS DITA 1.0 specification did not yet have the abstract element. I recall the design workgroup at IBM struggling with whether to call shortdesc an abstract, and the name shortdesc won out in the version of DITA that was eventually adopted as OASIS DITA 1.0. The shortdesc element as originally defined seemed to be adequate for most online information at the time. But after DITA 1.0 began to see wider use, the OASIS DITA Technical Committee started to get feedback that a more inclusive scope of introductory input was needed. This could be done by subsuming shortdesc within this new “abstract” container that would be much richer than shortdesc. “Just how rich?” you say? Well, after the committee got done designing that horse for DITA 1.1, you could pretty much develop your whole topic within the abstract if you wanted to. But just because you can doesn’t mean you should!
How do you decide if your topic needs an abstract with one or more shortdescs in it or just a standalone shortdesc? To me, the standalone shortdesc is like an American baseball pitch (to cricket fans that’s the throw, not the grassy lane)–focused, deliberate, powerful, whereas the abstract allows you to take a bit more of a run at the subject, like bowling the ball in a game of cricket (to baseball fans, a proper bowl looks like throwing a wild pitch. All clear to everyone?).
Did you know?
Having thoroughly and alarmingly mingled two international sports with two versions of a document standard like a true committee, let’s go out on some more practical advice.
Besides the excellent suggestions already in the DITA Specification since version 1.1, Kris Eberlein made this observation in a forum discussion about the abstract element:
“The abstract element has several interesting uses:
- “To hold multiple shortdesc in a conref (reuse) file
- “To produce a more complex thesis statement at the beginning of a topic
- “To contain multiple shortdesc if you want to filter that element”
Deep Dive
- DITA 1.2 Spec: abstract
- http://tech.groups.yahoo.com/group/dita-users/message/10067
- Comparison of cricket and baseball (where HBP and LBW are mutually incomprehensible concepts)