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
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.
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”:
We want user assistance that will:
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:
(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:
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).
Since I started working with DITA, my best source of information has been the dita-users Yahoo group. This is the only place on the web where I can ask questions about DITA and know that I will get a reliable answer, usually very quickly. But Yahoo groups aren’t exactly “high tech”. They’ve been around since 1998, and their format hasn’t been updated recently. They’re not easy to search, answers are provided over multiple pages, and the layout isn’t optimal, to say the least.
So I was quite happy to see a proposal to create a dedicated DITA Q&A forum on Stack Exchange, a platform I have found very useful when looking for programming info (on Eclipse, Tomcat, etc.). This site is very well designed, the answers are often very useful (and easy to read!), and the interface offers many interesting features, such as voting on answers.
But to get launched, the site needs to reach 200 “committers”, people who commit to use the site for three months. So… please go the DITA staging area and commit! It will only take a minute of your time. Even if you’re just curious about DITA, or getting started with it, this Q&A forum might be very useful to you in the long run.
And if you really want to commit, read this post from Anders Svensson, who came up with the initial idea.
While DITA doesn’t provide a dedicated variable mechanism like the one in FrameMaker, variables can be easily implemented in DITA using keydefs, keyrefs, and keywords.
There are a few different ways to create variables in a DITA document; this is the method that we use at IXIASOFT. It requires a basic knowledge of keyrefs; the DITA 1.2 feature article on Keyref overview is the best article I’ve read on the subject.
Our approach is to create a map that is dedicated to defining keys for information that varies per project but that has the same value throughout the document, such as product name, product version, book names, etc. This map is then referenced from any other map that needs to access this information.
To use variables in DITA:
<keydef>element, as shown below:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd"> <map> <title>ACME Product A Variables</title> <keydef keys="Product_Name"> <topicmeta> <keywords> <keyword>ACME Mobile</keyword> </keywords> </topicmeta> </keydef> <keydef keys="Product_Version"> <topicmeta> <keywords> <keyword>1.0</keyword> </keywords> </topicmeta> </keydef>
<mapref href="Product_A_variables.ditamap" format="ditamap"/>
<keyword>element, as shown in the example below:
<li>To install version <keyword keyref="Product_Version"/> of <keyword keyref="Product_Name"/>, follow this procedure:</li>
Et voilà! You could also specify your keydefs directly in your map, but isolating them in another map makes it easy to reuse the information.
I struggled a few weeks ago when trying to make a cross-reference to a figure in DITA, so I decided to document the procedure here. It might be useful to other DITA writers (and I’ll know where to go should I forget how to do it).
Two DITA elements are used to specify figures:
<fig>: Provides a context to display a wide variety of content. It is mostly used to display an image specified with the
<image>element. It can optionally include a title. You need the
<fig>element to make a cross-reference.
<image>: Specifies the actual artwork or image. It can be specified outside of a
<fig>element, but in this case you cannot make a cross-reference to the image.
To make a cross-reference to an image:
1. Create a
<fig> element and set its
2. In the
<fig> element, insert an
<image> element that points to your image.
Your code should look something like this:
In file topicA.xml:
... <topic id="topicA"> ... <fig id="my_figure_id"> <title>Technical details</title> <image href="my_figure.jpg"/> </fig>
<xref>element with the following structure:
<p><xref href="topicA.xml#topicA/my_figure_id"/> shows the technical details of the product.</p>
Et voilà! It’s pretty simple once you know how to do it.
On a personal note, I recently started working as the main technical writer for a company called IXIASOFT. They provide two products: a database that stores XML documents (called TEXTML Server) and a DITA content management system (called DITA CMS).
I’m very excited! I love being the only technical writer with a bunch of developers and the company’s two products offer very interesting challenges. One product is quite technical, so I’ll be writing SDK guides and documenting sample code, which I love. The other one is a GUI targeted to technical writers, so it will be very interesting to write for an audience that I know very well!
I see some very exciting times in my future :)
I started writing documentation using DITA and Oxygen over a year ago. How I wished DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA had been available at that time!
I knew enough about DITA to get started, thanks to a great weeklong training from Comtech Services (JoAnn Hackos’s company). I could create concept, task, and reference topics and organize them into a DITA map. I knew the basic elements and how to make simple hyperlinks, but I still had so many questions: What are the advantages and disadvantages of using the different types of links? Why would I want to use this tag instead of that one? How do I use conditional processing correctly? DITA Best Practices answers all these questions.
Too many technical books focus on procedures or reference information, without answering the essential question: why? Why should I perform these procedures or use these tags? But that’s not the case with DITA Best Practices, which provides descriptions that are focused on user needs and tasks. Many of the other DITA resources are tag-centered; if you don’t know the name of the tag, how can you know that you’re supposed to use it?
This book is divided in three parts:
The book also includes many examples, first providing the DITA code and then showing how the code would be displayed online, which I found very useful.
I highly recommend DITA Best Practices, whether you are just getting started with DITA or want to improve your DITA skills.