Migrating to DITA : skip & clean…but keep the Shortdescription!

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!

Sacrilege!

For experts Michelle Carey (« DITA Best Practices » co-author) and Kristen Eberlein,the « short description » is the inevitable part of your procedure. Skipping the Short Desc means putting your DITA project success at stake. Without <ShortDesc> you deprive users from the benefits of essential DITA features: progressive disclosure and searchability.

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.

« 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?

“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