Laura Katajisto, Microsoft Corporation

XML and content management systems have been used to produce support materials for Nokia phones, tablets, and their accessories since 2003. We began with our own proprietary DTD but switched to DITA when DITA1.2 was approved and have developed three different versions of our CMS. This article gives you a brief history of our XML journey and provides lessons learned in our CMS development projects.

From Proprietary DTD to DITA

In the beginning, our content creation was the same as in many other companies. The site, team, and purpose of the document decided what tool and format were used. Each project had its own user guides, a shorter guide for the sales boxes, and a longer guide for the CDs, DVDs, and later also Nokia web sites. Reuse was ad-hoc and done with copy-paste, content and layout resided in the same file, and guides were written as complete documents from table of contents to index. Each project paid content creation, translation, and publishing costs because all phases were repeated for each individual project.

Our XML journey started like they usually do—the promise of saving costs, time, and effort was too tempting to ignore. The XML DTD that we designed had the necessary elements for the user guides that we had produced at the start of the project. However, our business environment and portfolio had already changed during the development phase, and, in the end, the DTD didn’t quite match with what we needed to produce.

We used the DTD over 10 years with our two first CMS versions, stretching it as much as we could, but gradually the system actually became a problem. We needed to deliver DITA for online purposes, and the transformation process from our own DTD to DITA through multiple different publishing pipelines between databases was time-consuming, very error-prone, and difficult to troubleshoot.

When DITA 1.2 was approved, we began to develop the latest version of our CMS. DITA had already been used elsewhere at Nokia for years, but for our team it hadn’t been an option before because of the lack of support for variables. Reuse has always been one of the biggest drivers in our information product creation, and variables are the enabler for our high reuse rates—all changing but compulsory product-specific information such as product names are marked as variables in our content.

We started small and used only “basic DITA” in the beginning. We did some domain specialization, but wanted to keep our content as standard DITA as possible because of interchange reasons. As we became more confident with DITA, we started to explore the more advanced possibilities on our own, without the encouragement of our developers. We started using subject schemes for controlling metadata, conref push in all its formats, mapref push, and so on. We also improved our way of working and designing the deliverables, making content creators happier by simplifying and streamlining their work and managers happier because we again saved in costs.

Lessons Learned from Our CMS Development Projects

We have learned quite a few things during our three CMS development projects, but the following six are those I want to emphasize. The lessons may sound simple, but strangely, they aren’t that easy for several reasons, from time to money to human resources.

1. Get your basics in order
Even though it may sound self-evident, it’s important to get the basic structures of your development project into good shape. Assign a team, and let them dedicate time for reading before the project starts. This investment pays off later, for example in speedier requirement analysis. Ensure that the team is cross-functional, because that helps to avoid silos. You may also want to have a bit tighter schedule than necessary, because keeping the quickly approaching goal in mind can keep up the drive to complete tasks. However, for a tight schedule to work, you must not be penalized if you don’t meet those schedules, and you must also know your team and your environment because tight deadlines in a large-scale development project can also stress people so much that development stalls.

2. Give responsible people the authority to decide
Divide development into different streams, such as content creation, information design, and translation. Name one person responsible for each stream. Depending on the size of your project and company, include one or more members in each stream. We had one person per stream, and that person had the absolute authority to decide on matters of that stream. This authority helped us avoid both endless discussions about the pros and cons of each option and the danger of decision-by-committee. Members had over 10 years of experience in their particular area, and even though they discussed problems and solutions with other people in that area, they were the ones who made the decision and were accountable for it.

3. Do end-to-end development and later testing
I’m sure everyone has experienced that “oops” moment where everything is almost ready and then something rather important, like translation expansion, has been forgotten. To avoid this, have representatives from all phases of information product creation involved: information design, writing, translation, and publishing. If every area is represented in meetings and mails, it’s easy to remember and discuss, for example, the translation aspect when making decisions about writing. During development, draw preliminary process flows and task charts that show the relationships so that you can adjust when you notice that some item wouldn’t work later when you move from one phase to another.

4. Run a pre-pilot project
No matter how much you plan, draw, and test, there’s no better way to see how your new system performs than using it for real work. I strongly recommend doing a pre-pilot project in the new system. Of course, that’s not always possible, and, even for us, the third CMS development project was the first time we had a pre-pilot project. A pre-pilot project allows you to test the system in all phases of information product creation. You’ll see if you’ve made sound design decisions and can still change them if needed, you’ll see what the potential bottlenecks are, and you’ll find out what parts of the system or processes still require more attention. We involved people from our operation teams at this point and trained them to use the new system. The content these teams created was later used in the first real projects, and the move from pre-pilot writing to real project writing was hardly noticed by the writing team because they were already so accustomed to working in the new system.

5. Steer away from proprietary DTDs
Even though it may seem like a good idea to create your own DTD to match your needs, that decision may turn out to be a problem later. Proprietary DTDs may be difficult to extend to fit the demands of a changing business environment. DITA is a standard and has long release cycles, but development happens globally and you don’t have to do everything yourself. Proprietary DTDs may also lead to a tool lock-in, especially if you need to do a lot of customisation to make your DTD work with the tools. With a proprietary DTD, it’ll be harder to find developers, and you need to train users from scratch. With a standard DTD like DITA, you can expect that your new writers have some experience with it.

6. Hold two-way demos
During your development project, hold show-and-tell sessions to show your developers how you use a certain feature now and explain why you request it to be changed or improved. It might not be easy for developers to understand the finer nuances of information product creation, especially if they haven’t been working with you for a long time. Similarly, have your developers show you how they have planned to implement your features while they are doing the implementation. That way you can have a sneak preview of what is being developed and can influence it in case you notice there’s something you would rather do differently because of your business environment. Early reviews also help you prepare test materials and training materials in advance, so that you are ready to go when the implemented feature is deployed.


We have fond and not-so-fond memories of our development projects, and we remember both the hard work and the fun times we had during them. The third and latest CMS is the best one, flexible, quick, and easy to use. Like any development project, there are things that we would now do differently and things that we would still like to fix. If we ever start a fourth CMS development project, we will most certainly study our lessons-learned documents to avoid old mistakes and repeat the old successes.

Nokia devices and services functions were acquired by Microsoft in 2014, and the events described in this article took place and lessons were learned before the acquisition.