DITA Migration is like house removal: you’d better get rid of the unecessary stuff and clean your files BEFORE you move on. Don’t hesitate to skip and clean!
Following this rule, a 2014 DITA Europe Conference participant who wanted to reduce the volume of her documentation decided to skip all Short Descriptions...
Not only was this an example of misunderstood minimalism, but this is plain nonsense!
Right below the topic title, you MUST add a « Short Description ».
In the <ShortDesc> you’ll explain WHY the <task> is of interest to the user. Why should he follow these steps and which result he can expect after performing this task.
In short, the ShortDesc lets the user decide whether he should dig further in the topic.
In his article « Reflections on Writing Short Descriptions« , Dr Tony Self describes Short Descriptions as
“quality summaries that work effectively as overview paragraphs in a topic, and as progressive disclosure devices.«
Lost in Search…
When perfectly crafted, this paragraph provides you with a meaningful summary of the topic, i.e. the <ShortDesc>. Since it is extremely useful, you should not hide or skip this part!
If your objective is to help users quickly find the answer to their query, you can’t ignore the Short Desc.
Short Description is hard work
In their article « Editing DITA Topics: The Changing Role of the Technical Editor in the Age of DITA and Topic-Based Authoring », the IBM team stresses the usefulness, but also the difficulty of drafting Short Descriptions:
« Short descriptions are also key retrievability aids because they can appear in search results, as hover text for links or underneath child links. Writing one or two sentences that serve all these purposes well is difficult, and so editors must provide guidelines and examples to help our writers create effective short descriptions.”
Writing Guidelines for Short Descriptions
- Don’t repeat the title
- Don’t include steps (instructions)
- Provide the right/useful information
Shortdesc and minimalism
When trained in minimalism, technical communicators recognize here the 4th minimalist principle where the user wants to « read to locate some information »
To locate the info, the user has the (precise) <title>
To locate the RIGHT information, users need a meaningful, context-aware summary: the Short Description
DITA task missing context?
DITA opponents complain they are missing the « narrative minim » in DITA topics.
“Narratives work by placing certain facts of ideas in evidence, then drawing out a conclusion from the threads of those facts and ideas… But unless the user is fully contextualized and is genuinely in need of only a single data point, what the user needs when they are in trouble is the narrative minim that will get them out of trouble…
This is why we need topic-based content: because the book-scale narrative is too big for the modern impatient reader. They want quick answers — but they also want answers that work. They want the narrative minim.
A chunk of text sized to optimize for reuse is not necessarily… the narrative minim. Can you create a narrative minim by stringing together pre-existing chunks of content?
Perhaps, but it will certainly require deliberation and care to do so. What is clear is that without that care to construct the narrative minim when reusing chunks, the result will not be an effective narrative, but a collection of statements without narrative flow between and through them. »
Indeed, DITA does provide a narrative minim that is included in the topic: the Short Description. This is particularly the case when users “are in trouble [it] is the narrative minim that will get them out of trouble”. The Troubleshooting topic (DITA 1.3) for example recommends to insert, immediately below the title, the Short Desc