Skip to Content Skip to Main Navigation
 

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

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 Defined

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):

  1. 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.
  2. Determine which way to use the DITA OT (XML editor or Command Line Interface and notepad).
  3. Install the XML editor or use notepad to create content in DITA format.
  4. Publish using the XML editor or by downloading and running the DITA OT with ant scripts.
  5. 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.
  6. Use DITA according to standards you established with the new tools and modifications you implemented.

Tools Considerations

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 comes with the DITA OT installed and uses it to create output in multiple formats. If you don’t want to learn about or modify ant scripts, then you never have to, but provides a way for you to tinker with them, if you prefer.

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

Be Sociable, Share!

4 Comments

  1. By Alberton 20th, April 2015 at 7:14 am

    This article provided me with the exact information that I’ve been looking for to get started with DITA. Thank you Hannah for writing this.

  2. By Scott Kettereron 13th, November 2015 at 1:08 am

    Thank you for this excellent article. I have a question. When large organizations adopt DITA do they tend to get engineers involved with the development of DITA content or is it too complex for that, leaving the work to trained technical writers.

    Is an engineers time best used adding value to their engineering work (so that they collaborate with an expert technical writer instead) or do they tend to invest in the considerable training required to bring an engineer up to speed. I know that high quality content is important so, from your experience, how do large companies assign DITA writing.

    Thank you in advance,

    Scott

  3. By WAI_editoron 17th, November 2015 at 2:23 pm

    Scott – thanks for you comment. I suspect it’s like anything else – depends on the organization and its philosophy, but I’ll open it up to others who have had direct experience in a large company that used DITA.

  4. By Eric Hoffheiseron 6th, May 2016 at 6:32 pm

    I’m glad I came across this article. I’ve been a lone or near-lone writer for the last five years, and I’ve never been able to come up with a compelling use case to attempt a DITA implementation in such an environment. There’s learning how to implement it, learning some tools, paying for those tools (ouch), and at the top of the list, selling a new paradigm to managers who do not have a technical writing background.

    This article has given me a great place to start learning more about the implementation process and whether I could pull it off a DITA implementation in a small writing group.

    Thanks!

Leave a Reply