This article provides some insights into how you can help your team move to DITA successfully. It is not a complete description of DITA, nor is it a how-to. Instead, this article provides you with some understanding of what DITA is and, more importantly, some of the things you need to consider when moving to DITA.
What is DITA?
DITA is the fastest growing XML content standard. It is becoming the standard for Technical Documentation and it is being adopted for learning materials, business documents and pharmaceutical materials. DITA stands for Darwin Information Typing Architecture. I always find it more meaningful to look at the acronym in reverse order.
Architecture
IBM started off with the goal to create commonly structured content for sharing and reuse. To do this they developed an architecture to provide a common set of guidelines for how to build content. When we have guidelines and a common way of structuring our information, it makes that information much easier to create and much easier to share.
Information Typing
When we analyze content, we see various types of information. For example, on average, technical documentation consists of 60% procedural (task-oriented) content. Originally, DITA was developed to support technical publications, particularly software-oriented Help materials. Therefore, DITA provides structures for the following information types:
· Concept – Conceptual-orient (descriptive) information. Used to provide context or understanding.
· Task – Task-oriented (procedural) information. Used to define “how to” information.
· Reference – Reference-oriented (look-up) information. Used to define specific, often detailed information, or to bring together at-a-glance information (e.g., in tables) that is referred to (consulted) on an as-required basis.
You can use these standard information types to build unique sets of information. Typing information makes us think more clearly about what kind (or “type”) of information we are authoring so that it is consistent and coherent.
Darwin
Often, Charles Darwin is described as the “father” of evolution. He was a naturalist who proposed the idea that life has evolved over time from common ancestors.
IBM assumed that DITA will evolve over time to support a broader range of information types. In other words, it’s not static. If you need another information type such as a troubleshooting topic, then DITA has been designed to make it possible to develop that “specialized” topic and still ensure it is consistent with the standard information types.
Definition
Strangely, it is really hard to find a short definition of DITA. We suggest the following:
DITA is an open-content standard that defines a common content structure that promotes the consistent creation, sharing, and reuse of content.
Topic-Based Authoring
Authors transitioning from traditional Desktop Publishing tools and non-structured authoring frequently wrestle with the question “What is a topic?” Usually, Help authors do not have this sort of problem, as the approach to creating Help systems is topic-based. But authors who are accustomed to writing user guides or reports and are moving to DITA sometimes find it difficult, especially when they are deciding how to move legacy content into DITA.
From the technical-document perspective, we sometimes describe a topic as a single answer to a single question. This works well for Help and reference guides. For example, How do I create an email address? What is an email address? What is the syntax of the print statement? These all fit the one question, one answer, and one topic idea well.
Typically, authors have fewer problems identifying task-based topics than they do concept topics. Is the information that precedes a task part of the task or is it a concept on its own? A couple of questions to ask are “Can the concept stand on its own? Would it be possible to reuse the concept?” If the information is uniquely tied to the task, then it probably shouldn’t be in a concept on its own.
Structured Writing
Typically, the primary challenge of using DITA involves issues associated with structured writing. It is one thing for authors to follow corporate writing guidelines, but it is quite another to have to follow a very specific, mandated structure.
Often, DITA’s rigorous structure can prove difficult for authors, particularly if they are unsure what kinds of content goes into the structure. For example, should the short description be the introductory paragraph, or is the short description only used in searching and not displayed in the content? If authors are unsure about what content goes where, they will likely guess and “shoe horn” content in any way they can.
Following are four main steps to help authors write structured content.
- Content analysis and mapping to DITA – It is very important for you to conduct a content analysis of your information to determine its structure, then map your structure to the DITA information type structure. This exercise is best done with your senior authors who know the content intimately and can provide suggestions for how to handle problematic content. This exercise provides a clear understanding of how your content can map to DITA and if there are any challenges you will need to address. For example, one of our clients had an illustration of the product with every step. Where do you put the image? In this case, we decided to put the illustration in the “info” tag. If you don’t make these decisions in advance, you could end up with inconsistencies between different writers.
- Create writing guidelines – DITA provides a structure, but it doesn’t provide guidelines for your company’s best writing practices. If you have existing corporate standards, map them to the DITA structure, making it clear how authors should write each and every element in a DITA information type.
- Create a best practices example – Nothing helps authors understand requirements better than examples. Put together best-practice examples of each type of content.
- Train – While you have probably planned to have technology training (e.g., DITA authoring tool or content-management system), we highly recommend that you plan for a structured-authoring workshop for authors in advance of the technology training. Give authors an analysis exercise to do and have them map their existing content to the DITA structure. They will very quickly see how DITA can work for them. We find that it helps authors to better understand the concepts and better prepares them for the technology training when they trained in structured writing first. Learning to use the tool and learning structured content is a bit like learning to drive a standard-shift car while you are just learning to drive, which is much harder than it needs to be.
Collaboration
In the past, technical communicators tended to create a “document,” or particular Help most often working on their own to create the content. Sometimes a team of authors created content for a product suite. DITA really emphasizes the reuse and sharing of content.
While content could just be reused between different sets of documents owned by a single author, most often it is across multiple authors’ content. To do this, authors must work together collaboratively as a team for development. This does not mean authors are no longer responsible for owning their information or that they will lose control over the structure of the final output. Rather, it means that someone may be responsible for writing the core information (the information that is reused) while others are responsible for identifying how the information set needed for a specific solution differs from the core and adding information that covers those differences. Or it may mean that a number of authors work on different aspects of the core and work together to ensure that all the information is integrated.
Component Content Management System (CCMS) or Not?
The question of whether or not to get a content-management system is a tough one to answer these days. No matter what you do, technology costs money and money is scarce right now. So first, let’s start by answering whether or not you really need a CCMS.
Along these lines, the question of whether a content-management system is needed for DITA is essentially the same as asking if a content-management system is needed at all. If you answer “yes” to most of the following questions, a CCMS may be appropriate.
· Do you have lots of authors (greater than 10)?
· Are your authors in multiple locations?
· Do you have a large content suite?
· Do you translate your content?
Probably, your least expensive system is going to be a SaaS-based system. Software as a service, or SaaS as it is commonly known, is software you pay for on a monthly basis, which is similar to leasing. The software is hosted by the vendor and all work is accomplished via a browser. The software may or may not include an authoring tool. Most CCMS vendors provide a SaaS version of their software and all support DITA.
Some companies are contemplating Wikis for content management. Certainly you could go this route, but Wikis won’t offer you much more than what a well designed file system provides.
If you are having a tough time justifying a system at this point in time, consider code management software. Definitely not a real substitute for a real content management system, but it will allow you check content in and out and track status.
Alternatively, see if your company has an ECMS (Enterprise Content Management system). Vendors like EMC Documentum, IBM FileNet, and Microsoft SharePoint all support DITA now. If they are already in house, all you need is a few licenses. However, some technical knowledge is required to get these systems set up for DITA. This brings me to my final point.
Technical Resources
While much of the technical aspects of DITA can now be hidden under the covers of WYSIWYG authoring systems and enhanced user interfaces in the CCMS, DITA is still a much more technical solution than unstructured content. You will need resources in-house or a consultant to get you up and running, and probably need some help keeping you up and running. If possible, we recommend you select someone from within your organization. Someone who really likes getting into the “technical stuff” would be good in the role. A solid skill set includes knowledge of:
· DTDs
· Authoring and publishing style sheets, particularly using the DITA Open Toolkit
· DITA specializations
· Workflow (CCMS)
· Repository design (CCMS)
Conclusion
Clearly, moving to DITA takes some up-front analysis and planning to ensure a successful project. And it is important to support your authors every step of the way with guidelines and training.
About the Author
Ann Rockley is President of The Rockley Group, Inc. She has an international reputation for developing intelligent content management strategies and underlying information architecture. She has been instrumental in establishing the field in online documentation, single sourcing (content reuse), unified content strategies, and content-management best practices. Rockley is the primary author of the new book “DITA 101: Fundamentals of DITA for Authors and Managers” ISBN 978-0-557-07291-0 available from Lulu. You can reach her at rockley@rockley.com, http://www.rockley.com/.
