DITA: Know What You’re Getting Into
Editor’s Note: This was the feature article in this month’s TechCom Manager newsletter, reprinted here with permission. Click the previous link to subscribe to the newsletter.
by Hannah Kirk
A search for DITA XML will present you with tens, or possibly hundreds, of articles about the enormous ROI of XML authoring and DITA. And it is true. Most organizations have large amounts of material that can benefit from DITA. We can all agree that reusing content across publications is better than copying, pasting, formatting, and reformatting. And it leaves us with more time to actually write.
XML authoring and DITA in particular can save organizations much time and money, especially if the organization needs to create multiple kinds of output, has to reuse content, or translate.
If you agree this sounds great, you may be thinking, “How do I get started?”
And, that’s when it gets confusing. You can read books, attend conferences and webinars, and research vendors. But you probably won’t get straight information on how exactly to start using DITA and how smooth (or bumpy) the road to getting there will be. It’s not like you can just download DITA and get going. Or can you?
As I Got Started
When I researched DITA for my organization, I found that no matter the source—books, conference sessions, vendor presentations—things like costs and conversion to DITA were commonly discussed. But real information about the difficulties of implementing DITA was hard to find. It was even more difficult to find information about the steps I would have to take to get from authoring in MS Word to publishing great DITA content. This is probably because the steps are too complicated for a short session or article. Also, the steps can vary widely depending on the organization and its needs. Since every company’s needs are different, it is difficult to derive from others’ stories what you will need in tools, experience, and time to set up and use DITA.
DITA is a technical XML standard. It is not a tool. Theoretically, the DITA open toolkit (DITA OT) is usable right after downloading it, but most people cannot use it right away. It takes proper tools, proper knowledge, or both to set up and use the DITA OT to create output that truly meets your needs. And, it takes time.
IBM created DITA. In 2005, they donated it to the OASIS (Organization for the Advancement of Structured Information Standards) technical committee. Since then, they have released two additional versions (DITA 1.1 and 1.2). With each version comes more stability, clarity, help, and features. But the DITA standard and the DITA OT are maintained by volunteers. No one is paid to make DITA work well, make the style sheets look good, or to write good, thorough documentation for the DITA OT. It uses free, open source tools (ant scripts, Apache FO) which may or may not do what you want them to do.
Whether selecting a new method (writing structured, minimalist content for reuse), a new standard (topic-based XML spec DITA) or looking for new software to help you reach your goals (XML-enabled authoring tools), it’s critically important to ensure that the tools you select support your needs today—and can do so well into the future.
So, essentially, DITA is still in its early days. Not quite infancy, but toddlerhood. It is still developing. It is still stabilizing. The kinks are still being worked out. This means that implementing DITA requires some risk on the part of the adoptee. A person or group implementing DITA needs to know how to set it up and troubleshoot.
Taking the Plunge
Before you make the move, consider some well-known factors (ROI, time commitment, cost, etc.) and the less well-known factors about implementing a DITA solution:
- How comfortable are you with writing code and experimenting with new tools?
- Do you have a high tolerance for technical difficulties?
- Do you like trying to figure out how to make things work, especially when the solution is not clear cut and you may have to buy a new tool or hack together something to make another tool work (again and again)?
- Are you and your team willing to commit to a completely new way of thinking about and writing content?
If you don’t like experimenting with new tools, figuring out how to make things work, or troubleshooting technical difficulties (and you can’t pay someone to do them for you) then DITA might not be for you.
To consider the less well-known factors, you should know what to expect technically.
Taking Steps to Make DITA Work
Getting DITA to work requires several steps, some of which can take months. If you perform these steps by yourself, you will have to read books, take classes, attend conferences, and read between the lines in many cases (unless you hire someone to do this for you):
- Find out the technical components of DITA and how to implement them according to best practices. Analyze your organization and figure out exactly how DITA works and how you can use it to meet your needs.
- Determine which way to use the DITA OT (XML editor or Command Line Interface and notepad).
- Install the XML editor or use notepad to create content in DITA format.
- Publish using the XML editor or by downloading and running the DITA OT with ant scripts.
- Figure out what you don’t like about the DITA output. Then, figure out how to modify it to appear the way you want it to.
- Use DITA according to standards you established with the new tools and modifications you implemented.
Now that you know what steps are associated with implementing DITA, you may be wondering about what tools are required.
At a minimum, you will need:
- The DITA OT
- An editor (you can use Notepad, but I don’t recommend it)
- Knowledge of how to use ant scripts
More likely, you will also need:
- An editor (probably
, Xmetal, Arbortext Editor, or structured frame)
- The DITA OT (which might come with your editor)
- A rendering engine (like Render X or Antenna House) for making your PDFs and HTML help look better than what you get with Apache FOP (the free rendering engine that comes with the DITA OT)
- An XML expert to create and modify your style sheets for you (or knowledge of how to do this so you can do it yourself)
- A CCMS (Component Content Management System) or some kind of version control
- Knowledge of how to make the Editor, the CCMS (which probably runs on some kind of server you’ll need to set up), the DITA OT, and the rendering engine work together to allow you to write, edit, and publish documentation. Depending on the tools and the support you have, this can either be no big deal or maddeningly frustrating.
Next, you need to know in what order to implement these tools. Should you implement the DITA OT with ant scripts, or use an editor with rendering capabilities built in? Should you use a CCMS with the editor built in? Should you get the CCMS to manage your content first, or should you use an the editor without a CCMS?
The answer to these questions is harder to quantify. Using ant scripts to render DITA is difficult if you have no coding experience and no desire to learn. But, if you enjoy programming, this might be a fun task. And, if you want to use DITA but have no money to buy an editor or CCMS, this is a way to get started.
For those who are more risk averse, a good XML editor or CCMS will hide many DITA challenges. For example, Synchrosoft
Most XML editors and CCMS systems use the DITA OT on the back end to create output. They also use style sheets to create output. If you like the way the output looks, you never have to learn how to modify a style sheet. But if they do not work for your organization (and they probably will not), you will have to modify them yourself or pay someone to do it for you. And if your content renders well with Apache FO (which doesn’t support some DITA features like indexes or special fonts), then you won’t need to find workarounds or pay for a rendering engine. But chances are good you might.
Future of DITA
As time passes on, DITA will become more stable and implementing it will become easier. Five years ago, I wouldn’t have had the tolerance or resources to figure out how to implement DITA myself. But now, there’s enough information and expertise available that it isn’t as difficult as it once was—especially if you have some technical ability. And this will only continue to get better with time. So, for the most risk-averse of us out there, DITA might not be right solution right now, but in a few more years, it could be.
About the Author
Hannah Kirk is a Technical Writer at Cryptography Research, Inc. in San Francisco, CA, where she is implementing DITA, an XML authoring tool, and a CCMS as a lone writer for herself and a team of engineers. She has experience in many authoring tools and CCMSs and has authored technical documentation in functional (and non-so functional) structured and unstructured environments.
More on DITA and XML Authoring
- Calculating the Financial Impact of DITA for Translation
- Authoring in XML — Why Start?
- XML Authoring: Coming to a Desktop Near You