One of the subjects Doug Kim covered in his TCUK14 presentation, on the changes to Microsoft’s user documentation, was how Microsoft now normally begins its Help topics with an empathetic statement. The writers seek to understand the user at the moment they’re reading the content.
For example, if someone is reading the topic on auto save, it’s likely they’ve just experienced a crash and have lost some data. So they express empathy by saying, crashes happen:
By doing this, Microsoft is moving away from the norm – the generally accepted way to structure task topics in DITA and other standards is to dive straight into the task without any introduction.
We think Microsoft has go this right – there is often a need for empathy in technical documentation. Of course, this is difficult if your content could be reused anywhere – you lose the understanding of the user’s point of view. However, being empathetic, from the research Microsoft carried out, is what users, today, prefer.
See also: Trends in Technical Communication Course – Advanced Technical Writing Techniques
You make a good point, Ellis. We technical communicators need to bear this in mind, at least when writing for consumers and other non-specialists.
And even when we reuse content, we ought be able to do this at least to some extent — for example, by using metadata or DITAVAL filtering.
Thankfully, DITA tasks do include a tag, though, and context can also be included in the element. So, even if “the generally accepted way to structure task topics in DITA and other standards is to dive straight into the task without any introduction”, it doesn’t have to be that way.
BTW, I hope that Microsoft doesn’t make a habit of using the word “stuff”!
Corrected first sentence of my original comment: “Thankfully, DITA tasks do include a Context tag, though, and context can also be provided in the Short Description element.”