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.

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…

Indeed, when searching for an info on the Web, you probably appreciate reading the small paragraph displayed SearchingInformationright below the searched title.

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

RepeatingTitle

  • Don’t include steps (instructions)

ShortDesc_Instructions

  • Provide the right/useful information

ShortDesc_Better


Shortdesc and minimalism

Minimalism-the-perfect-amount-of-somethingWhen 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

TSI_ShortDesc


Conclusion:

Doing DITA ? Never forget the <shortdesc>!


 

 

.

 

Laisser un commentaire ?

Anti-spam *

ERIKSON
GSX
COHERIS
SCHLUM
EFFICIENT
OPTIS
INTERSEC
NMJ
TALEND
LYRA
HILL
HORIBA
ERIKSON
GSX
COHERIS
SCHLUM
EFFICIENT
OPTIS
INTERSEC
NMJ
TALEND
LYRA
HILL
HORIBA

logo-bleu

Établissement de formation à la documentation technique

Formatrice : Marie-Louise Flacke

Graduate of the American
University of Paris
Tel. 06 03 20 50 10

… mais que signifie Awel-A-Ben ?

Contact

BLOG

blog-icon

 

PRESS

press-icon