Richard Forster, Information Architect & Documentation Specialist
After 5 years of building and managing a DITA infrastructure for technical publications in a global MedTech company, here are my 5 key lessons. Some of them we got right from the beginning, some we learned the hard way—and some we never got around to implement properly…
Lesson #1: Think big, start small
DITA is a technology to revolutionize your user assistance. Both the content production process and the actual formats and customer deliverables can and will undergo huge changes and improvements once you start adopting DITA. However, for a successful move to DITA the adventure needs to be broken down into manageable parts.
Getting accustomed to a new writing philosophy, a new syntax, a new text editor, a new content management system, and new output formats is pretty daunting. Do not try to combine all of this together; try to go in smaller steps.
Do not convert all content to DITA in one big bang, but start with pilots and migrate in ascending order of complexity.
Do not try to start with a reuse strategy that reuses topics or even sentences or phrases across all your deliverables, but start more modestly, accept some redundancy and strive for continuous improvement.
Lesson #2: Think engineering
Successful writing in DITA requires an engineering mindset. If it is not already the case, make sure that tech pubs is an integral part of the engineering process.
Versioning, document control, release management, configuration management—do not only understand the engineering processes and strategies, but find ways of aligning your own documentation activities and structures with engineering reality.
Otherwise you will struggle forever to keep your documentation in line with engineering requirements and to resolve the extra dependencies created by the mismatch between documentation and engineering. Reuse and single-sourcing are two of the biggest promises of DITA, but they remain elusive if not embedded in a global strategy fitting the engineering environment.
“Think engineering” also means “think code”. Treat DITA like software code. Use content management systems, collaboration systems, quality and test tools, build files and automated scripts just as you would do with any other code.
Lesson #3: Think meta
Care not only about your data (content), but also about the data about your data (metadata). Writing and collaborating on thousands of small topics requires a much more careful approach to metadata than handling a few dozen large monoliths in formats like MS Word, FrameMaker, or RoboHelp.
Identify the metadata that is needed to efficiently manage the content and work with it—from the perspective of both your customers and your tech pubs personnel. Find the best ways to capture that metadata and to keep it up-to-date, accurate and free of redundancy.
Find the right level to attach your metadata and always avoid maintaining metadata manually if the system can do it for you.
Do not collect metadata for its own sake.
And never collect metadata for its own sake. Whenever you plan to implement some metadata (for example, if you design a structured approach for entering comments in the version history), make sure there is a concrete purpose for the metadata, that the metadata can be accessed efficiently, and that the people gathering the metadata know why they are doing it and what for.
Lesson #4: Think localization
DITA content is typically not just produced for a single-language audience, but for an international audience requiring translation into dozens of languages and cultures. Using DITA with its clean separation between content and form promises a much more efficient localization process and better quality control.
However, these advantages do not come for free and the localization part has to be planned for. Not only will you require a suitable tool chain and translation partners who can deal with DITA, you also need to write (or rather code) your content in a way that allows for a smooth translation process. This goes far beyond traditional guidelines for neutral, unambiguous, and context-free writing, it also has a considerable impact on your content architecture.
Often a compromise is required between what is best for authoring and what is best for localization.
Creating books with hundreds of reused topics, steps, and other content chunks might be a brilliant approach to keep your source free of redundancy and inconsistency, but it may turn the localization process into a nightmare with the number of dependencies exploding exponentially. Often a compromise is required between what is best for authoring and what is best for localization.
Lesson #5: Think metrics
DITA will not only fundamentally change the way your writers and translators work, it will also change the roles and tasks you will have to fill in your tech pubs department. The cost structure is likely to change and you may need to open new positions on one end, while saving headcounts on another end.
Sooner or later you will need metrics to show the impact of DITA, to demonstrate the cost saving, the efficiency or quality gain, or to justify a new position. If you do not want to compare apples and oranges, you have to think very hard and very early about what to measure, and then measure consistently and diligently. Just counting and comparing the number of pages or words written or translated is useless when the underlying content structure has changed completely, when you have no way of measuring the rise (or fall) in documentation requirements, or when the shift of responsibility from external vendors to internal personnel is not accounted for.
A content management system may give you hundreds of beautiful figures and pie charts, but they are likely to be worthless.
Typically it is not the measuring part that is the most difficult, but establishing what to measure in the first place. A content management system may give you hundreds of beautiful figures and pie charts, but they are likely to be worthless once you think about them.
Instead, identify the business questions that need answering and then deduce metrics that can help you with concrete answers to those questions. Only then you can start measuring something meaningful. You will not regret it.
About the Author
Richard Forster holds a PhD in computational linguistics and is an expert in text engineering. He was the lead information architect and documentation systems engineer at Varian Medical Systems from 2010, when the DITA CMS was introduced, to 2016.