(This is the second post in the Learn DITA on Your Own series.)
Before you can create your first DITA project (the “World’s Smallest DITA Project”, which will be the content of my next post), you need to have a basic understanding of DITA. There are tons of articles on the topic, but many of them focus on the advantages of DITA, its business case, or the benefits of single-source documentation. That’s all well and good, but our objective here is to learn how to write documents using DITA. Therefore, let’s get started with the following article, written by Chris Benz:
This article provides a great overview of DITA and its main concepts. Note that it was written for instructional developers and trainers, so you can skip the introductory paragraphs, jump directly to “What is DITA?”, and stop reading at “What is the DITA L&TC Specialization?” (unless you’re an instructional developer, in which case you’ll find this section very interesting).
So now I’m going to assume that you’ve read the article and know some of the basic DITA concepts :)
Now you know enough to get started! In my next post, I’ll take you through the whole process of writing a topic, creating a map, and generating your output. You’ll create the ”World’s Smallest DITA Project” and go through the following steps:
Coming next week: The World’s Smallest DITA Project.
For the more curious
It provides a very nice high-level crash course on the DITA language.
In a series of articles on the continuing growth in the use of DITA across the States, DITAWriter Keith Schengili-Roberts stated that “job postings seeking DITA experience continue to grow while FrameMaker usage continues to decline.” Clearly, knowing DITA can be a very important asset in a technical writer’s portfolio.
While at the STC Summit in Atlanta last spring, I met many writers who felt stuck in their careers and wanted to learn new technologies like DITA. But they couldn’t afford to take time out of their schedules to attend a two-day training course in another city and, understandably, their employers wouldn’t pay for training not applicable to their current roles.
But it is possible to learn DITA on your own, if you know where to start!
The Internet is full of resources that you can use to learn DITA independently, at a very low cost, and at your own pace. A few years ago I felt stuck in FrameMakerLand, and learning DITA made a huge difference in my career. I want to share my experience and provide fellow writers with the resources they need to get started with DITA on their own.
This is the first in a series of posts to help you learn about DITA. I plan to cover the following topics:
The information and the tools are out there, and you can learn DITA on your own if you know where to look. I’m hoping that this series of posts will make this process easier for you!
Coming next week: a DITA 5-minute crash course
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. :)
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 :)