Update: Links to all session slides and recordings are grouped here.
I’ve been a technical communicator for nigh on 20 years. I teach technical communications. I theorize about technical communications. And for all this time, I have steadfastly held to the great rule that you do not mix concepts with tasks.
DITA has three major topic types. Two of them are Concept and Task. Why? To keep them separate, of course – everyone knows that!
And yet – and yet – and yet – here I am, telling you that “everything we know is wrong.”
Why am I saying this? Because in today’s information environment, in today’s world of intelligent, adaptive, responsive, mobile applications, you need more than procedures to know how to use software. You need to know:
- Is it really interesting for me to do this – i.e., will it help me solve my problem, or get my work done, NOW?
- Once I learn this procedure, can I do other procedures without having to learn them, too?
In other words, we need to learn to use and understand our applications on a very different level from even a few years ago. We need to embed concepts in our procedures so that once you learn one, you can generalize to others.
It turns out, that cognitive theoreticians, including John Carroll, the father of minimalism, knew this. Our colleagues in training know it. Why don’t we? Why aren’t we leveraging what cognitive scientists have learned about learning as part of our user assistance?
Update: Some of these questions were treated in my webinar series, sponsored by Adobe, A Cognitive Design for User Assistance.
- The first session, on January 15, covered how users have become learners and showed some real world attempts to deal with that. You can watch the recording here.
- The second session, on January 29, covered user assistance as a learning experience meant to empower users through the acquisition of basic concepts, with examples of how to use DITA topics to do this. Watch the recording here
- The third session, February 4, dealt with how results of collective know-how from crowd sourcing, social media and related techniques can be used to create learning materials that are, themselves, circulated to widen the community. Watch the recording here
Rant of a Humanist Nerd 
I’m looking forward to your webinar series, Ray, especially because from what I understand so far, I think I may disagree with you… 🙂
I think *contextual* information very much has a place inside task topics – but I don’t think that it preempts a complete concept topic which is justified in its own right. Also, I find that the separation of concepts and tasks helps me to efficiently maintain my documentation, because Individual tasks tend to change faster than the underlying concepts.
But I will pay close attention, because I can be sure to learn a lot from you!
Hi Kai,
with all due respect, we are not here to help ourselves do documentation more easily. We are here to help the user do her or his task more quickly and easily. John Carroll knew that you learn by doing. Many folks have misinterpreted him to mean you don’t need concepts at all, even – not true.
The big question is, “how much concept do you need?” – stay tuned.
Hey – you didn’t argue with me at TCUK when I suggested this! We could have had some good fun!
I’m not out to make it easy on me – but I do need to figure out how to give my customers the most bang for the buck my employer shells out. And efficient maintenance is a secondary concern to the primary one you mention.
Oh, and I think we had plenty fun at TCUK – or so I seem to remember… 😉
“we are not here to help ourselves do documentation more easily. We are here to help the user do her or his task more quickly and easily.”
Ease of production and quality of output shouldn’t be in competition. I’ve seen a lot of scenarios where production delay creates a disparity between the documentation and the reality documented that’s more harmful than the marginal improvement that the longer production time buys. It’s that old “perfect is the enemy of good” thing. If anything, ease of production should enable better documentation, not worse.
Welcome to the league of tech comm heretics, Ray. I’ve been ranting about the tyranny of the terrible troika for a long time now. (http://everypageispageone.com/2012/07/28/the-tyranny-of-the-terrible-troika-rethinking-concept-task-and-reference/)
I think this mistake that tech comm has made here is to mistake an analytic truth (task, concept, and reference, are useful divisions of information types for analytical purposes) with a synthetic idea (task, concept, and reference material should be presented separately.
This was certainly not the idea in information mapping, from which the idea of information typing entered tech comm. Information mapping was about how to put different information types together to create an effective document. Somewhere along to way, though, this synthetic truth got lost and tech comm started separating concept and task, for no better reason than that they were different types of information.
It definitely time to challenge this unfortunate practice.
Mark, from your comments above, I think I’m in good company 😉
Ray, Thanks for the thoughtful, thought-provoking read. And Mark, I’m with you that the “mistake that tech comm has made is to mistake an analytic truth (task, concept, and reference are useful divisions of information types for analytical purposes) with a synthetic idea (task, concept, and reference material should be presented separately.”
A yarn metaphor comes to mind. Information typing helps writers untangle concept, task, and reference material. But untangling isn’t the goal. It just shows you what you have to knit with.
I just thought that I’d tell you that I love your evolution image on your home screen. That’s great. I’m taking a doctoral course on technology’s influence on and interaction with society and culture, and that illustration fits the course just perfectly.
Thanks – I’ve been rather fond of this image for some time, even though it’s been used, even overused, quite a lot. I think it hits a certain nail right on the head.
Ray, you wrote:
(a) “you need more than procedures to know how to use software.
(b) “You need to know:
– Is it really interesting for me to do this?”
(c) “We need to embed concepts in our procedures”
You also consider DITA does not provide such features/does not respond to the user’s need for conceptual information.
You (together with Kai, Mark and Marcia) may have a look at “Reflections on Writing Short Descriptions” by Maxwell Hoffmann:
http://blogs.adobe.com/techcomm/2013/06/reflections-on-writing-short-descriptions.html
“Short descriptions …serve to:
– advise the reader of the significance and relevance of the topic
– help the reader decide whether to continue reading the topic
– help the skimming reader understand the central theme of the topic without reading the remainder of the content
– answers the reader’s questions of “what” and “why”.
QUESTION: are you sure (DITA) “Short descriptions” are not EXACTLY responding to your requirements?…
For additional info on writing Short Desc, check Kris Eberlein and Michelle Carey’s articles.
Well put, Marie-Louise. And Max’s article nails this point. Thanks.
Marie-Louise, when you say “You also consider DITA does not provide such features/does not respond to the user’s need for conceptual information” you have misunderstood me by 180°. In fact, I have shown in many presentations (go look on my slideshare site) just how DITA CAN be used to embed concepts in procedures, even right in steps, using components such as , , and as well as the you mention. I also show how I use as part of a progressively disclosed enhanced tool tip to do just what we are talking about.
I suggest you re-read what I wrote about the three webinars I did for Adobe. In the description of the second, it says,
“The second session, on January 29, covered user assistance as a learning experience meant to empower users through the acquisition of basic concepts, with examples of how to use DITA topics to do this.”
Seems to me that’s what you want to see, no?
I should have added, that DITA can be used in this way WITHOUT BREAKING ITS INHERENT SEMANTIC STRUCTURE.
Oh dear, another correction – I forgot that WordPress doesn’t like angle brackets, so when it says “using components such as” – follow by “stepresult, info, choices, choicetable, as well as the step result you mention. I also show how I use step result as part of a progressively disclosed enhanced tool tip to do just what we are talking about.”
Apologies for confusion.
Should you feel like a need for an update on DITA authoring, you may join some of the following events:
(a) Information Development World, San Jose, CA – Oct. 22-24
You’ll have the opportunity to attend some presentations by DITA experts, such as Michelle Carey, Mark Lewis, Amber Swope and Leigh White
(b) DITA Europe Conference, November 18-19, 2014 in Munich , Germany
http://www.infomanagementcenter.com/DITAeurope/2014/index.htm
(c) DITA Boot camp
http://comtech-serv.com//index.php?main_page=index&cPath=28_1_146_5
(d) Building reusable learning objects in DITA
http://comtech-serv.com//index.php?main_page=index&cPath=28_1_146_153
In the meantime, you could have a look at “How we use minimalism and a new form of task-oriented Help, WalkHub, to overcome cognitive Load in Web applications”
“We found that DITA principles can build a strong foundation for a new tool that follows
the way people actually perform tasks online. To this end, we developed WalkHub, an open source, step-by-step, interactive tutorial and documentation tool with DITA concepts in mind.”
Click to access BP2014-02vanTomme_Lakatos.pdf
I would be happier if the above comment didn’t promote mostly events sponsored by one single entity for whom Marie-Louise works – with the exception of the Information Development World conference (where, by the way, I am also speaking, though on a content strategy topic, not DITA).
(a) I don’t work for the above-mentioned entity. I am extremely happy and proud to work occasionnally -on a project basis- for them. It’s a real pleasure to contribute to high-quality projects.
(b) re. DITA: apart from Kris Eberlein and Michelle Carey, you may also follow (and check your information with) M. Priesley, of IBM.