DITA and double embeddedness
I’m not a fan of webinars, since they’re usually nothing more than a glorified sales pitch. They’re presented as best practices—e.g., “How to best present information to users”—but after a few minutes it becomes obvious that the best way to present information to users is to buy the presenter’s product. Not exactly what I was looking for.
That was not the case with a series of three webinars I attended a few weeks ago, A Cognitive Design for User Assistance. Written and presented by Ray Gallon, technical communicator, instructor on Information Architecture and Content Strategy at Paris Diderot University, and author of the very interesting blog Rant of a Humanist Nerd, this presentation was by far the most stimulating I have attended.
The first webinar in the series, Users become learners, explains how we need to see our users as learners and how we must apply ideas from cognitive development theory to the design and execution of user assistance.
This blog post summarizes at a very high level what I took away from this great presentation, but I highly recommend that you listen to the recording of this presentation on Adobe’s website (see Ray’s blog for the details). It’s an hour very well invested.
The concepts: Cognition and Context
- Users learn best when the information they need to perform a task is available as they are performing the task.
As writers, we often think that the documentation gives meaning to the product, but it’s actually the other way around. The product gives meaning to the documentation. Without the product, a manual has no meaning. You can read the best user guide ever written on a product, but until you have worked with the software, the documentation is too abstract to be meaningful. Users learn about how to use a product by doing something and making connections.
- Users learn best when they understand why they are performing a task. They need to know quickly if they need to perform a task. They need concepts as they are performing their tasks.
This goes a bit against what we’ve been told in the past years: Tasks and concepts must be separated. In fact, DITA provides two different types of topics for tasks and concepts, implying that these two types of information should not be mixed. But if you don’t know why you are doing something, how can you learn to do it?
The solution: Double embeddedness
The solution is what Ray Gallon calls “double embeddedness”:
- Embed the user assistance directly in the user interface.
- Embed simple concepts directly into the user assistance.
We want user assistance that will:
- Give users all the information they need and only the information they need.
- Deliver that information when they need it, which means at the moment they have real work to do.
- Put a sentence or two of conceptual information in context (while the user is performing the relevant task) to reinforce knowledge acquisition and integration.
- Explain why it is interesting to perform a task, again in one or two short sentences.
- Embed the user assistance in the UI in such a way that:
- The user can find it immediately, without excessive searching
- If the user doesn’t need the help, it stays out of the way
And the beauty of this approach is that DITA is the perfect vehicle to implement double embeddedness. In his presentation, Ray demonstrates a user assistance system in which:
- When users hover over an element of the UI, a pop up is displayed with a short overview of the function. This information comes from the <shortdesc> element of a topic.
- If a user needs more information, clicking on the question mark in the pop-up displays simple conceptual information about the function: what does it do and why should you care? This information comes from the <body> element of the topic.
- The tool tip pull-down also contains related links to a detailed task or more conceptual information, which are provided through <related-links> elements.
(Image copyright: Ray Gallon. You should watch the presentation to get the full benefits of the demo)
The demo also implemented progressive disclosure, which recommends the following:
- Initially, show users only a few of the most important options.
- Offer a larger set of specialized options upon request, and disclose these secondary features only if a user asks for them, meaning that most users can proceed with their tasks without worrying about this added complexity.
I was so inspired by Ray Gallon’s presentation that I met with my development team yesterday to present his findings and recommend that we apply them for this new product we are working on. We spent part of the afternoon brainstorming how to best apply these principles in our product (I work with great developers!). We came up with a different DITA implementation, and I hope to present it here when we have fully implemented it.
I love my job. :)
(Coming soon: Part II of this presentation: Empowering User/Learners Through Cognitive Development).
My name is Nathalie Laroche and I’m an extreme technical writer. 
Hi Nathalie et bonjour,
Thank you for this post- I’m glad my presentation has been useful for you. Please contact me, as I’m interested in the solution you are working on – you can make first contact by LinkedIn. Also, some of your Ixiasoft colleagues have my email address.
Bonjour!
I’ll be more than happy to share our solution with you! Our API is pretty clear by now and we’re working on the display. We should have something that can be shown within a few weeks.
Thanks for your great presentation! :)
Nathalie
Hi Nathalie – love the ideas of embedded user assistance and progressive disclosure. We have yet to embark on the DITA journey. We feel like our content set is not yet large enough to warrant it…but we could just be in denial:). Love your blog – ‘Extreme Technical Writing’ – what an inspiring name.