Used wisely, the <shortdesc> element is a great way to offer sneak peaks into a topic – useful if you need progressive revelation or have ‘readers that don’t read’.
In any topic, <shortdesc> element sits between the <title> and <body>. As a general principle, its purpose is to tell the user what the topic is about so that they can make a decision whether or not to read more.
There’s an art to writing a good <shortdesc>, to the extent that many users initially make the decision not to use them. On the surface it seems a redundant repetition of the rest of the article – fluff. But with care and a consistent approach they can offer readers something genuinely useful.
Here’s an example from HTC on a topic about doing a factory reset:
If HTC One max has a persistent problem that cannot be solved, you can perform a factory reset (also called a hard reset or master reset). A factory reset reverts the phone back to its initial state – the state before you turned on the phone for the first time.
In 50 words, that <shortdesc> tells you when and why you might need a factory reset, and the outcome of that action, so you have a pretty good idea of whether the rest of the article is relevant and it may even answer your question without reading any further (for example if I’ve looked up ‘hard reset’ to find out if that action will wipe all my data).
But there’s more! The <shortdesc> also acts as a link preview on web outputs, so it help users to decide if that link is a destination they want to go to. That’s why Don Day says:
“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.”
Another key benefit is that a well-crafted <shortdesc> that makes use of key search terms is more findable – if the content is available to public search engines, they will tend to display the short description as part of the search results – again, helping see whether the information on offer is useful. Here’s how the same example from HTC looks in a Google search:
<shortdesc> being used in Google search results
Bearing all this in mind, you may want to keep the <shortdesc> quite minimal, so that it’s a neat length for the link preview but make use of the <abstract> element for a slightly chunkier summary. That gives a good three-stage phased reveal into the topic.
Next time we’ll talk about the <abstract> element in more detail, but in the meantime you can get involved with the Bitesized DITA project on Twitter. Tweet us your DITA tips, suggestions and feedback on @BiteSizeDITA