Bitesize DITA: Using the <abstract> element

Building on the previous article about the <shortdesc> element, we’re going to take a closer look at <abstract>.

In its simplest form, abstract does exactly what you’d expect — offers a long-form summary to the topic. You can use abstract very much in the way it is used in traditional print materials.

The Abstract element allows more complex markup than shortdesc, that is, there are more elements that the content model allows within abstract than within shortdesc. In fact, abstract is flexible enough that you could almost put your entire topic contents inside it (you shouldn’t, but it’s possible). Paragraphs, lists and tables, for example are permitted, giving you more to work with when introducing your topic.

As well as acting as an introduction to your topic, abstract has some additional clever uses. For example you can set up a library topic and store several shortdesc elements inside an Abstract element and then reuse them by conref – useful if you have recurrent short descriptions you want to reuse.

If you want to publish different short descriptions for different audience profiles, you can also put multiple short descriptions inside the abstract element and then filter them accordingly using DITAVal. So you may, for example want different short descriptions for novice and expert users.

When it comes to processing, there is no reason why shortdesc and abstract need to be visually distinct in the output, but because they are separate elements you can, if you want to apply different styles to shortdesc and abstract. So you have the option to treat the shortdesc and abstract as a seamless whole, or to visually identify the shortdesc for the purposes of progressive disclosure.

If you’ve ever been frustrated by the limitations of the <context> element in a task topic, abstract also provides a better alternative because:

  • It’s in a more suitable and obvious location for this kind of introductory information, straight after the title and before the body – where the user needs it and is likely to read it.
  • You can only use context within a task, but you will probably need some kind of contextual information in all topics – using a universally applicable element.
  • When used in a task topic, it comes before the prereq element, whereas the context element comes after that. It is arguably more suitable to have contextual information before prerequisites, as you need the context first to determine whether this is the right task for you to accomplish your goal.

In our enthusiasm for reusable content, in-topic contextual information has been neglected in the past, but its value is becoming more and more apparent. Abstract provides an elegant, flexibly and semantically rich way to deliver that.

Do you have a question about the DITA standard? Tweet us @BiteSizeDITA