CIDM

Summer 2025

THE DITA TALES
– a bumpy ride implementing DITA in a small documentation team

Photo of smiling woman with short dark hair.

Justyna Hietala, Beamex Oy Ab

Who are you, dear reader, who has stumbled upon this story?

Are you a lone technical writer facing the challenge of moving to structured documentation? You have no idea how to do it or where to even start. You’ve only heard about this “DITA” thing and that it’s quite cool, but haven’t done any work with it yet.

Or maybe you and your small team are preparing to take the “big step” into the DITA world. You have a plan and support from the experts. Perhaps you’re a bit nervous but, nevertheless, confident that this will go well.

Or are you already using DITA? Maybe you migrated to structured documentation some time ago, and you’re happy with your setup. But have there been glimpses of doubt about whether things could be done in a better way?

You might even be part of a large documentation team, sitting comfortably in your technical writer chair. Occasionally, you take a quick look to admire your professional setup for producing the best user documentation there is: a fancy CCMS and a few other advanced tools to help you carry on with your daily tasks. Like a well-oiled machine, the system works like a charm, big cogs turning in perfect harmony. Every now and then, you wonder “How do other people manage without a setup like this?” or “How do smaller teams tackle these issues with limited budgets?”

Regardless of your background, buckle up! I’m going to tell you a story of a one-person documentation team taking on the challenge of implementing DITA in a medium-sized company. You’ll soon learn that implementing DITA is not an easy task, especially when you’re doing it alone, alongside your everyday responsibilities. So, get ready and join me on this adventure – you might just find some inspiration for your own journey.

DITA? Never heard of it, but apparently everyone else had

My story begins with a younger version of myself, moving to Finland, hoping to find a dream job. Then I saw a job ad for a technical writer. While it didn’t sound overly exciting, the position matched my profile, so I applied for it, and I got the job. I remember thinking to myself “writing manuals —what a boring job… but it will get the bills paid and I can continue searching for a better job” in the meantime. It was my first job, and it sparked my interest in technical documentation. We were using a basic text editor without any content management system, so every now and then I found myself wondering whether there was a better way of doing this.

That was the first time I heard about “structured documentation” and “DITA”, but to be honest with you, I didn’t have the motivation or the actual need to start learning. Little did I know, I would soon find myself looking for a new job, where the lack of DITA really came back to haunt me. It appeared that all open technical writer positions required some level of DITA knowledge, and I had none.

After a long and exhausting search, I was lucky to be offered a job as a technical writer at Beamex. They told me that they wanted to move to structured documentation and guess what? I was the one who was going to do it!

Mapping the legacy content – Welcome to the jungle

In the beginning, I had to give a presentation about why moving to structured documentation was a good idea. What would we get from it? What were the benefits? How much money would we save? To be honest, I had no idea. I couldn’t tell whether we would actually save any money!

With just two people on the team, where the senior writer handled the daily documentation needs, I was able to focus all my energy and time on research.

To better understand our needs, I started by mapping the existing documentation, tools, and methods. What I found was daunting, to say the least:

  • About 70 different manuals and other documents of different lengths, different translation needs, and different frequency of updates.
  • All legacy content spread across nearly 700 MS Word documents.
  • An additional 200 MS PowerPoint files, including screenshots and drawings, used in the manuals.
  • Content localized into 13 languages.
  • One person handling everything.
  • No content management system and no version control system in place.
  • Deprecated Doc2Help tool used to generate .chm help files.

Are you feeling as overwhelmed as I did back then, thinking about the size and complexity of this solo project? How do you even start a project like this on your own? Quick answer: You don’t. You hire an expert to help you get started. And that’s exactly what we did.

The XML format face-off

I was told by a few experts that XML is ‘the’ format to go for. A format that best supports the main principle of structured documentation, allowing the split between layout and content.
Among XML formats, there were three potential candidates:

  • DITA
  • Lightweight DITA
  • S1000D

I quickly ruled out the S1000D format as our expert explained that it’s mostly used in the aircraft and military industries. That left us with Lightweight DITA and DITA. After listening to presentations on both, with my knowledge at the time, it felt like Lightweight DITA would be somewhat limiting, with less software support and fewer online resources. So, I decided to go with DITA.

The experts estimated the whole migration would take about 1-2 years. Sounds reasonable, right?

Wait… we need what now?

When you have zero knowledge in some area, even simple things are not obvious. I didn’t know that you need a publishing environment when you use structured documentation. I didn’t know a CMS would be useful to manage a rather large number of DITA files. I didn’t understand the complexity of the task ahead of me. There were so many different blocks that, when put together, would build a functioning system to author and publish user documentation. And, as a solo flyer, I had to understand and implement all of them. Piece of cake! Especially when you can get your hands on a fancy what-you-see-is-what-you-get UI system and don’t have to deal with whatever’s happening under the hood. Or even better: tools with full technical support to set the whole environment up while I get to enjoy the beautiful art of writing content. No command line. No code. No exhausting legacy content transfer. Perfect.

But what happens when your budget is limited? When the documentation team is just a small part of the company and documentation isn’t the main focus, there’s very rarely money available to invest in a project like this. Our setup was simple: a tool for authoring, DITA Open Toolkit for publishing—and no CMS. Yep, you read that right. NO CMS. Between me, my supervisor, and the soon-to-be-retired technical writer, none of us had any idea just how many files we were actually dealing with.

Learning DITA with cats, dogs, and calibrators

Once we knew the environment to work in, I was free to focus on learning DITA—the only skill I thought I would need to learn. Keep dreaming, small-town girl…

But fear not, dear reader —surely, the almighty Internet is full of free courses and articles on DITA, right? Well… not that many resources available, unless, of course, you are interested in Dita Von Teese or fancy sunglasses.

I ordered a few books and took a very basic online DITA course. The mismatch between the course content and its practical application was significant. Here I just learned what conkeyrefs are all about, based on an example of dogs and cats, while in front of me was a manual for a very complicated calibrator which should somehow change content dynamically.

I decided to start small, with an attempt to print a simple DITA topic to a PDF. That experience was somewhat challenging and left me convinced that I couldn’t do it without proper education. Luckily, I had an amazing supervisor who saw me struggling and threw me a lifeline in the form of extensive DITA training.

The MC6 Family – Lead the way!

I could no longer postpone the inevitable. It was time to start the migration process. Once again, I carefully studied our company’s documentation and saw one product family that seemed like the perfect guinea pig to test my new skills. The cornerstone of Beamex product portfolio is the MC6 Advanced Field Calibrator and Communicator. The MC6, along with its younger brothers the MC6-Ex and MC6-WS would pave my way toward the structured documentation world.

All three devices belong to the same product family which means they share the same architecture, components, and functionality which unequivocally means that their user manuals share much of the same content. Before diving into the migration I first had to check what was hiding behind the final PDF of the user manual. What I found was daunting.

Each product had its own manual, each chapter was a separate MS Word file, each chapter had a separate PowerPoint file with screenshots, and each chapter had its own folder with untranslatable images —that equals a LARGE NUMBER OF FILES.

Now let’s multiply this by three:

LARGE NUMBER OF FILES x 3 = OVERWHELMING NUMBER OF FILES.

The translations situation just added to the complexity—the English language version was up to date for all three products, but all other languages were either way behind or non-existent.

Too much structure, too soon

There were a few things to consider when planning the information architecture:

  1. The legacy manual had a horizontal layout with two columns – is this something my primitive setup can handle?
  2. All the screenshots were embedded in multiple PowerPoint files – should I save all of them one by one or take new screenshots directly from the devices?
  3. Due to differences between the devices, there were minor differences in the text and screenshots – how can I make them interchangeable depending on the product?
  4. There were static phrases describing locations, such as ‘see picture to the right’ and ‘on page 25’ – all of those had to be located and fixed to match the dynamic nature of DITA.

Based on my knowledge at the time and the given source files, I came up with the first idea for the information architecture:

  • I decided to ditch the two columns and the horizontal layout in favor of a single column in a classic vertical format.
  • A separate bookmap for each product.
  • A separate ditamap for each chapter.
  • A warehouse topic – I wasn’t sure why we needed it, but everyone said it’s a must…
  • Keys for product names.
  • Conkeyrefs for screenshots and images.
  • Profiling for unique product content.

Do you think this is a good structure? Let’s verify that with some visuals.

Does it look like a good structure now? Yeah, I didn’t think so either. Obviously, all the submaps were overkill—because how is this really different from the pile of MS Word files in the previous solution? I also spent a fair amount of additional time making backup copies, since we didn’t have any CMS or version control system. The entire process was long and heavily based on a trial-and-error approach.

No time to read the manual – the reality of being a one-person team

I wanted to rewrite the content, exploring the diversity and richness of DITA, but I didn’t have time. After moving those manuals to DITA, another 50 “active” manuals were still waiting for their turn.

My coworker retired and when you’re a one-person team, you’re the one who has to stay on top of current releases and their documentation needs. This makes it difficult to fully immerse yourself in the beauty and vastness of the structured documentation world or to explore all the extensive solutions DITA can offer.

With limited knowledge and time I may have opted for less-than-ideal solutions, even though they seemed like the best options at the time. We have a saying in Poland “A Pole is always wise after the damage is done.” I would indeed see in the future that my solutions were not as effective as I had thought.

Lost in translation

With a somewhat functioning version of the MC6 family product manuals, it was time to tackle the translations. I quickly found a perfect solution—or at least the only one I could see. It sounded tedious, but I guess that was the price we had to pay to get all the benefits from moving to a structured documentation model. “Let’s copy the existing MC6 structure, change the map language, and copy-paste the legacy content for all languages”. Brilliant right? I mean, what could possibly go wrong when you’re copy-pasting content in a language you don’t speak, after making changes to the English source text? We didn’t have an existing translation memory, and I didn’t know enough about the translation processes to have any other ideas at the time.

You may feel bad for your humble narrator, but don’t worry—help was on the way. Make way for the reinforcements—eager summer trainees ready and willing to rescue me from this uninspiring task.

If things weren’t intense enough, our R&D department was working hard on a new member of the MC6 family – MC6-T Multifunction Temperature Calibrator and Communicator, which again shared about 70% of the manual content with its older brothers. It would have been a smart idea to incorporate the MC6-T content into the existing MC6 family manual structure. Unfortunately, the pressure of the release deadline rushed the decision to once again copy the original DITA structure, build the MC6-T manual separately, and worry about combining them later.

DITA headaches and a new family member

Given all the aforementioned solutions, I found myself dealing with several headaches:

  • I had multiple copies of the same DITA structure and files.
  • I had multiple copies of independent translation projects.
  • As I was handling the daily documentation needs, I was faced with a continuous lack of time to finish the migration.

Just as the ‘DITA migration’ project was gaining momentum, it was about to be put on hold. I was about to begin a new, exciting chapter of my own story—I welcomed a new family member, this time into my own family. I embarked on the adventure of becoming a full-time mom to a sweet little boy.

One year on maternity leave resulted in many additional independent translations for MC6 family products, all of that with no CMS.

DITA here, DITA there, DITA, DITA, everywhere!

Let’s take a deep breath and flash forward to today. Where are we now?

  • We’ve doubled the documentation team resources, and our ‘documentation department’ consists of two people now.
  • We finally managed to move all our manuals to DITA.
  • Migration was completed in about five years, so only five times longer than the expert estimated.
  • We have around 10,000 DITA files.
  • We decided to keep seven leaflets in InDesign due to demanding graphics.
  • Our content is localized into 15 languages.
  • We’ve taken a version control system into use—even though it was not initially built for DITA, it helps us to maintain the file structure and gives us a safety net.

What about MC6 family user manuals? About a year ago, I started working on restructuring and refining that particular DITA project. I decided to combine all four MC6 family products into one ditamap. I finally have time to rewrite the content to follow our new style guide, making the manual text localization-ready at the same time. We rely on translation memory. We still use profiling, and we’ve started to utilize keys much more. I’ve come to love them! Can’t recommend these bad boys enough. I even managed to convince our software developers to create an automatic script for taking UI screenshots for any language!

The DITA Tales – The Good, The Bad, and The Migrated

All good stories must come to an end. Now that the dust has settled, let’s explore the benefits that this DITA migration journey has brought us. One of the biggest improvements has been the savings in translation costs. Submitting unformatted DITA content for translation has resulted in a higher percentage of translation memory matches, thereby lowering the costs. We are spending significantly less time on formatting and adjusting the layout of our documentation, allowing us to focus more on the writing, ultimately leading to higher-quality content. Let’s also note the advantage of having one source and leveraging reuse, which eliminates multiple copies of the same text.

While the benefits of this journey are clear, we must not forget the sacrifices along the way. We spent a significant amount of time learning and setting up the environment, along with additional time dedicated to the actual migration task. To get things started, we had to invest in training and necessary tools. We also had to tone down our fancy graphical layout to make room for dynamically published content.

 

And let’s face it, I made a few mistakes:

  • Multiple copies of the original MC6 structure files resulted in a complete loss of the reuse benefits.
  • Managing such a large number of DITA files without a CMS or at least a version control system was challenging.
  • Moving legacy translations through copy-paste was not only tedious but also error-prone. Without translation memory our translation process was doomed from the beginning. Perhaps a translation memory alignment would have been a better solution given the circumstances.
  • I didn’t take the time to make our content translation-friendly, which led to spending that time helping translators and solving inconsistency-related issues.

 

A happily ever after

As difficult and challenging as the journey was, I’ve learnt a few valuable lessons. Migration from an unstructured to structured documentation model is a complex task. Implementing it while maintaining everyday documentation needs is hard. Being a small team with no relevant knowledge prior to the process makes it even harder. However, taking this journey alone had its pros. I got to make a lot of executive decisions that ultimately affected the way I work on a daily basis. While long and bumpy, the road led me to victory, which felt amazing. This achievement gave me newfound confidence to believe that I am more than capable of overcoming difficult challenges while still finding beauty in the journey itself.

Take this with you, my dear reader: however demanding the circumstances, however overwhelming the task ahead feels, you can do it. You can achieve whatever you put your mind to.

About the author:

Justyna Hietala is a Senior Designer in Technical Documentation at Beamex Oy Ab. A passionate professional with almost 10 years of experience in technical writing and genuine interest in technology. Skilled in DITA and DITA Open Toolkit. At Beamex responsible for implementing DITA structured documentation model, creating the user documentation as well as creating, customizing and managing DITA-OT plugins using XSLT and XSL-FO for publishing.