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).
DITA Stack Exchange site: Let’s commit!
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.
Let’s commit!
Using variables in DITA
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:
- Create a map that will contain the variable definitions.
For example, I’ve stored my variables in a map called Product_A_variables.ditamap. - In the map, set your variables using the
<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> - Add your variables map to your main map:
<mapref href="Product_A_variables.ditamap" format="ditamap"/>
- In your documents, specify the variable using the
<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.
DITA Tip: Making a cross-reference to a figure
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 id attribute.
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>
3. In the paragraph where you want to include the cross-reference, include an
<xref> element with the following structure:
<xref href="topicfilename#topicid/figid"/>
For example:
<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 :)
Book Review: DITA Best Practices
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:
- Part I, Writing in DITA, is a great introduction to the basic concepts of DITA and provides tips and recommendations on how to write effective concept, task, and reference topics.
- Part II, Architecting Content, was by far the most useful for me. It explains how to organize your information so that it’s retrievable, organised, and reusable and covers in details topics such as linking, metadata, conditional processing, and content reuse.
- Part III, Converting and Editing, describes how to move an existing documentation set to DITA.
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.
Importing Code Samples with DITA (or How to Avoid Serious Headaches)
So now we know that good API documentation must include code samples. But if we want our users to base their code on our examples, we must make sure that they are valid and always up-to-date.
In general, the code samples are simply copied from the developers’ source files and pasted into the documentation. If the source code is updated after the documentation is released–for example, if a new mandatory parameter is added to the API–then the documentation must also be updated. Manually checking that all the code samples are still valid may be possible if the documentation is short and simple, but that is rarely the case when documenting APIs. Updating code samples manually can quickly become unmanageable (not to mention be the source of a serious headache, as I unfortunately had the chance to experience recently).
To solve this issue, the code samples in the documentation should be linked to the developers’ source files so that any change to the code will be reflected automatically in the documentation. In DITA, this can be done with the <coderef> element, which is available inside a <codeblock> element.
For example, consider the following source file:
C:\SVN_Checkout\product_x\src\samples\HelloWorld.java
class HelloWorld {
public static void main(String[] args)
{
System.out.println("Hello World!");
}
}
In the DITA XML file, the reference to this sample would be coded as follows:
<p>The following code shows the infamous "Hello World!" Java class:</p> <codeblock> <coderef href="..\..\SVN_Checkout\product_x\src\samples\HelloWorld.java"/> </codeblock>
When transforming the DITA file, the output would be similar to the following:
Some guidelines when importing code samples:
- The imported source files should be short and sweet; importing a Java class that goes over four or five pages in the documentation is not very useful (or readable).
- The source files should be well commented and include white space for readability.
- The documentation should be stored with the software, using a control management system, so that the paths to the source files are always valid.
One disadvantage of using <coderef> is that the source code cannot be formatted once it’s imported, so for languages with amazingly long class names (like Java!), it can be downright ugly. Another disadvantage is that <coderef> imports the complete source file, which is not always optimal. Sometimes I only want to include short sections from the source file. Fortunately, this can also be done in DITA, but it’s a bit more complicated.
Including code snippets
To include code snippets in a document, one solution is to create a script that extracts from the source files only the sections that are of interest to the documentation. The script looks for keywords in the comments, indicating the beginning and end of the code samples, along with an ID in a <ph> element uniquely identifying the sample. The output of the script is a DITA file that contains all the code snippets with their IDs.
For example, assuming that the script looks for the DITA_START and DITA_END keywords, a code snippet could be coded in the Java file as follows:
/** DITA_START:<ph id="helloworld_example"> **/
class HelloWorld {
public static void main(String[] args)
{
System.out.println("Hello World!");
}
}
/** DITA_END:</ph> **/
Running the script generates a valid DITA file (for example, dynamic_code_sample_library.dita) that contains the code snippet:
<codeblock>
<ph id="helloworld_example">
class HelloWorld {
public static void main(String[] args)
{
System.out.println("Hello World!");
}
}
</ph>
</codeblock>
The snippets are included in the documentation using conkeyrefs:
<p>The following code shows the infamous "Hello World!" Java class:</p>
<codeblock>
<xref conkeyref="dynamic_code_sample_library/helloworld_example"/>
</codeblock>
With this solution, I run the script to make sure that the code snippets are up-to-date, I generate my DITA output, and voilà! Well, that’s the plan anyway. I’m currently working on the script, so the headache occurs at the beginning of the project ;-) But I’m having fun and know that it will be worthwhile in the long run!
For more information on creating good samples
My name is Nathalie Laroche and I’m an extreme technical writer. Read more...
By PDGACO payday loans uk
