Karen Bertram, OpenMarket
During the past several years, DITA has caught the attention of many people in our profession, yet I still run into writers and instructional designers who either haven’t heard of it or don’t understand its purpose and value. This article is primarily for this audience and for those who have considered implementing a DITA-based solution but who do not have the budget or time to retool.
In this article I will focus on DITA’s principles and underlying methodologies and explain how to take advantage of them regardless of your authoring platform or process. Before getting started, let me say that the screen shots included in this article are intended to demonstrate certain techniques, not to promote the tool I currently use (Author-it). I hope that by the end of this article, you’ll agree that the principles and methods matter more than the tool!
The Important Principles and Methods
DITA is a set of XML schemas that prescribe content structures for three types of information that are common to computer user documentation. By understanding the standard information types (concept, reference, and task) and underlying methodologies, you can significantly improve the usefulness and usability of your documentation products. In a nutshell, here’s what you need to understand:
- The purpose of each information type and the content it contains
- Structured writing (a.k.a. topic-based writing)
- Basics of minimalism (understanding your users and including only the information they really need)
DITA’s Standard Information Types
Developing documentation that conforms to DITA’s three standard information types—concept, reference, and task—is challenging for writers whose point of reference is the delivered document—the manual, the guide, the book. There are two learning curves to tackle: the methodology known as structured writing and the information types themselves. Together these really change the way you author content!
This methodology is also referred to as topic-based writing. If you’ve ever developed an online help system, then you are already familiar with the need to break content down into smallish, standalone pieces, which you then assemble into a deliverable.
DITA takes structured content one step farther and prescribes information types and content structures for each type. This is incredibly helpful because it removes the head-scratching task of designing your own information architecture. DITA basically does that for you. It requires that you distinguish each piece of content as either concept, reference, or task, and then it requires that the content conform to a Document Type Definition (DTD) or schema. If this all sounds rather constraining, it can feel that way, but the constraints lead to superior document quality by improving content and structural consistency.
For the purposes of this article, I’m going to assume that you get the gist of structured writing and now turn the spotlight on the information types.
Conceptual content helps you understand why something is the way it is, why the product works the way it does, or why you might need to use the product in a particular way. Here’s how the DITA specification defines a concept topic:
â€¦a topic that answers the question what is? Concepts provide background information that users must know before they can successfully work with a product or interface. Often, a concept is an extended definition of a major abstraction such as a process or function. It might also have an example or a graphic, but generally the structure of a concept is fairly simple. — DITA 1.1 Language Spec
The DITA DTD for concept topics allows for paragraphs, lists, sections, and examples, giving you plenty of room to explain both simple and complex and concrete and abstract concepts. Two examples of conceptual content that I write frequently are XML element definitions and web service data flows. Although the XML element definitions consist of just one or two sentences, they’re quite valuable because of their reusability.
Example: Using a concept topic in multiple locations—
Figure 1 shows three views of content items in my Author-it library:
- On the left you see a stack of topic objects. Each one bears the title of an XML element and contains a short definition of it. The highlighted object is “carrierId”.
- In the center is the user interface that Author-it displays when you query to see which other objects use carrierId.
- On the right is one of the objects that uses the carrierId topic. The carrierId definition displays as shaded content, indicating that it has been embedded in the table. If you’re wondering why the carrierId element definition doesn’t also contain its characteristics (e.g., type and length), that’s because these characteristics can change based on the web service.
Figure 1: Using a concept topic in multiple locations
Example: Breaking down conceptual information—
Figure 2 shows two concept topics. One contains a sequence diagram and the other the related use case. I’ve put these in separate objects partly because they’re easier to find in the library and partly so that I can use them separately or together in the document deliverable. Although there’s no one right way to decide how small or large to make objects, the general rule of thumb is that the smaller you make them the more reusable they are. The tradeoff is that the more objects you have, the harder they are to find and keep track of, and this is where component content management capability comes in mighty handy.
Another thing to consider when breaking down content is how complex the concept is. Sometimes you need to decompose a complex concept and create multiple topics; the trick is to focus each topic on one concept, not several.
Figure 2: Two concept topics that explain how a particular web service works
Reference content is factual information that a user might need in order to effectively perform a task. For example, if you’re writing documentation for developers about how to use a web service, you’ll want a reference section or chapter that contains all the details about each operation, such as URL syntax, request and response body elements, etc. Or, if you’re writing a cookbook, you’ll want to include a list of ingredients and maybe a table of ingredient substitutes.
Here’s how the DITA specification explains the reference information type:
Use the reference elements to describe regular features of sets of things, most commonly the commands in a programming language. However, this format is also suitable for recipes, bibliographies, catalogues, and similar collections of structured descriptive prose. — DITA 1.1 Language Spec
Sometimes I’ve wondered whether a topic is a fact or a concept. Take term definitions, for example. Earlier in this article I showed XML element definitions as an example of conceptual content. I find Ruth Colvin Clark’s description of factual information to be helpful in differentiating facts from concepts. In her book, Developing Technical Training, Clark explains that” … a fact is a unique piece of information that must be individually held in memory to be known.” As an example, the term ‘web service’ is a concept, but the company I work for makes a web service called “Direct Billing”, and that’s a fact! And this particular web service currently supports five REST-style operations. That’s another fact.
The human brain is not particularly good at retrieving facts, which is why it’s important to gather them all up and give users a central place where they are easily found and to create links from task to reference topics (more on this shortly). And, as with conceptual content, it’s important to determine how to break down reference content so that it can be reused.
Example: Using multiple reference topics in a table of XML elements—
Figure 3 shows a table of XML request elements that draws from four topic objects in my content library. The table uses the element definition as well as all the subelement and attribute descriptions. These four objects are used in several request/response element tables in the document deliverable.
Figure 3: Using multiple reference topics in a table of XML elements
At this point you might be wondering how to decide which concept and reference topics to include in a given document. The answer lies in the task topic, which we’ll look at next.
Let’s start with the DITA definition of a task topic:
Task topics answer “How do I?” questions, and have a well-defined structure that describes how to complete a procedure to accomplish a specific goal. Use the task topic to describe the steps of a particular task, or to provide an overview of a higher-level task. The task topic includes sections for describing the context, prerequisites, actual steps, expected results, example, and expected next steps for a task. — DITA 1.1 Language Spec
As you can see by all of the elements available for task content, DITA gives you many options for structuring your information. However, if you’re not using DITA/XML, you can still create a task topic that conforms to the spirit of DITA, and that’s where the real value is. The rules of thumb to remember are:
- Cover just one task per topic
- Relate task topics to the concept and reference topics that users might need to refer to, such as workflows, field descriptions, and error message tables
- Relate task topics to other task topics that bear on the user’s ability to successfully perform the activity
Example: A task topic that uses the same content structures as a DITA task topic—
In Figure 4 I’ve highlighted the essential content elements of a simple task topic. As you can see, the DITA DTD provides for many more elements than are used in this example. With a more complex task, such as one that involves one or more user decisions, just refer to the DITA specification for guidance about how to structure the additional information. For example you might need to include a choice, or decision, table in a task.
Figure 4: A task topic that uses DITA content structures
If you’re curious whether this example breaks the “don’t mix information types” rule by including field descriptions (reference content), I don’t believe it does because the topic includes only expandable links to the field descriptions. The user does not have to view this reference content in order for the task topic to make sense. You could also link the task topic to the field description topics via “Related topics” links.
Why Task Topics Get Top Billing
Of the three information types, task topics are the most important because they tell users how to do something, which presumably helps them get their work done more effectively. They’re also important because they help you identify the concept and reference topics that you need to cover.
The process is basically this: once you’ve identified all your task topics, review each one and think about the concepts that users need to understand and the facts they need to have on hand to successfully carry out the task. Special terms almost always indicate a concept or two that need to be understood, and tasks that need to be broken down into subtasks may suggest a workflow that needs to be explained. Error messages are always candidates for a reference topic (or many), as are XML element descriptions for API documentation.
The exercise of going through your task topics, identifying concept and reference topics, and linking them together is referred to by some as topic mapping. Whatever you call it, I find it a rather fun exercise, and it will definitely help inform your time estimates. The key is nailing the task topics. With this in mind, let me devote a few words to minimalism.
The True Spirit of a Task Topic
There is a crucial idea in the DITA definition of a task topic that’s easy to skip over. It’s the idea that a task topic should help the user “accomplish a specific goal.” What is the origin of this idea? Back in the 1980s, John Carroll and several colleagues researched how people learn to use computer products. This work yielded the methodology known as minimalism. Like the minimalism you may associate with art and design, minimalism in the context of technical documentation and instruction encourages us to give users only the information they need.
Now, while it’s easy to create task topics that explain how to carry out some action using the product, it’s considerably more challenging to create task topics that explain how to do real work using the product. To meet this challenge, you need to understand what your users’ work goals are and how users interact with the product to achieve those goals. Unfortunately, many writers do not have the ability to conduct the kind of research necessary to attain this level of understanding. Nor does DITA solve this problem. However, by putting task content in the spotlight, DITA may be pressing writers to work harder to understand their users.
And here I’d like to draw a quick comparison between user documentation and technical training. If you ask a technical writer “What is the purpose of the product manual?”, the typical answer will be “To provide information that helps the user use the product”. If you ask a training developer “What is the purpose of the course?”, the typical answer will be “To improve peoples’ work performance by showing them how to use the product”. In my experience working with both writers and trainers, the trainers are more intent on understanding how the product will be used in a real work environment. Especially when training is instructor-led, trainers are loath to make assumptions about users. They know they can’t fake it in front of their audience. They must deliver instruction that is relevant and improves work performance.
Although I cannot propose a practical method for closing the gap between writers and their audiences, there are numerous books about product design, UI design, and technical training that provide great insights. (I’ve listed several at the end of this article.) Writers should take advantage of these resources and, in addition, have conversations with their coworkers in customer support, product management, and training to glean knowledge about users. In addition I can recommend using the Eclipse tool called Task Modeler. In conversations with SMEs, a graphical model of users and tasks helps facilitate the user-experience discussion.
Summing Up the Value of DITA
I hope by now you agree that DITA is far more than a set of content specifications and that you can get real value out of applying its principles and underlying methodologies. Here’s how I would sum up the value-adds DITA brings to technical documentation:
- Information types force you to be ultra clear about the purpose of any given topic. Are you trying to explain how to do something (a task topic) or explain how something works (a concept topic)? Or, are you providing factual information such as a table of data elements (a reference topic)?
- Topics that focus on one concept or task are easier and faster to read and comprehend, and they lend themselves to reuse.
- Task topics encourage you to find out how users will really interact with your product, not just how to click buttons and run apps.
- Structured content makes it easier to create repeating structures within and across documents, enabling the reader to see content patterns and more easily navigate the document.
- Review of topics can be faster than whole documents. (I say “can be” because SMEs require some training to get accustomed to reviewing standalone topics.)
- Information-typed topics are easier to reuse across multiple deliverables, resulting in greater consistency and leading to lower translation costs.
Suggested Reading and Training
- Comtech Services Workshops on Minimalism, Structured Writing, DITA, and others
- User and Task Analysis for Interface Design (Hackos, Redish)
- Software for Use (Larry Constantine, Lucy Lockwood)
- User-Centered Design (Karel Vrendenburg, Scott Isensee, Carol Righi)
- About Face: The Essentials of Interface Design (Alan Cooper)
- Introduction to DITA (JoAnn Hackos)
- Minimalism Beyond the Nurnberg Funnel (John Carroll, ed.)
- Developing Technical Training (Ruth Colvin Clark)
About the author
Since 1983 Karen Bertram has worked in the technical communications field, mostly as either a technical writer or techpubs manager, but also as a training manager and localization project manager. She began researching DITA, structured writing, and minimalism in late 2008 and conducted a successful proof-of-concept project in 2009. Currently Karen is a technical writer at OpenMarket, a division of Amdocs. A native of Seattle, Karen graduated from the University of Washington and still resides in Seattle along with her husband, two daughters, and one cat. She can be reached firstname.lastname@example.org.