Latest posts by techwriter (see all)
- 7 Tips to Write Great Essays - January 5, 2018
- How to Eliminate Abstract Nouns - January 3, 2018
- 3 Important Differences Between Academic versus Technical Writing - January 1, 2018
XML-based structured authoring has been one of the hottest topics in the technical writing community for quite a while. Shifting from traditional documentation to “structured documentation” has been the “holy grail” of top-echelon technical communicators for the good part of the last decade. In one survey reported by Scott Abel of The Content Wrangler, for example, 44% of the companies surveyed said they were using XML-based structured authoring. That’s an impressive number indeed.
Yet, as I can tell you from my own personal experience as a Fortune 100 technical writer, the transition is not always smooth and easy. Even though they are usually touted as the next best thing after sliced bread, structured authoring and platforms like DITA (Darwin Information Typing Architecture) have their own disadvantages and hurdles as well.
Here are five of them.
The most serious obstacle standing in the way of converting to structured authoring is this: perhaps you do not have a real need, a good business case why you should convert. Ask yourself: will your documents be read by customers in different countries talking different languages? Will the content of your documents be published in many different formats like PDF, HTML, digital content on mobile phones and pads, and even in publicly accessible kiosks? Will they be updated regularly or frequently? Will you reuse the same modular content in different combinations to create different deliverables? You need to give a strong “Yes!” answer to these questions to justify the conversion.
The transition takes a serious commitment of resources. You need to purchase not only a reliable, robust and scalable CMS (Content Management System) but also hire the correct SMEs (Subject Matter Experts) to lead and manage the transition. We are talking about an investment of not hundreds or thousands of dollars, but easily of tens of thousands of dollars, either paid upfront or budgeted monthly. In some cases the total cost can climb up to well over six figures. When they hear the real numbers, most small and medium businesses have a change of heart and decide that perhaps they should “wait a little more” before taking the plunge.
Structured authoring requires cleaning up the legacy files. DITA expert JoAnn Hackos of ComTech suggests four kinds of decisions that documentation managers need to make: 1) What to convert, 2) What to reuse, 3) What to rewrite, and 4) What to leave behind (see https://www.youtube.com/watch?v=x8lTRxzh7b0).
To get the management agree on all these four questions is a monumental task in itself since it can get political easily. Managers protect their own turfs and area of operation. Getting rid of certain documents, rewriting others, or changing their mode and scope of distribution affect their own decision making autonomy directly. So it sometimes becomes an inter-departmental battle to decide what to do with the legacy documents. That in itself may delay the conversion significantly as well.
Structured Authoring has a steep learning curve. Training not only takes time but money as well. You need to have a team of technical writers willing to make the transition by learning new tricks and devoting themselves to the conversion. When the team leader or one of the writers support the decision but the others don’t, team spirit and productivity suffer. Some writers love the way they traditionally do their job and they are threatened by this “new hi-tech mumbo jumbo.” It’s totally out of their comfort zone; and so they resist the process.
Thus even when the management commits the appropriate resources, internal staff conflict can make the transition a most unpleasant experience indeed.
Even if you answered all the above concerns satisfactorily, you’ll still need to structure the conversion, as all structured authoring experts agree. And by “to structure” this is what they mean: you cannot one day just start slapping XML tags to document components and think you’re converting them into “structured documents.” The conversion needs a much more comprehensive effort than that.
You first of all need a “Content Strategy.” You need to know where you are heading; how you will assure quality; how you will distribute the new content; how you will measure the results; etc.
After that, you need a “Content Model,” that is, which XML-based conversion platform are you going to use? Will it be DITA, one of the widely-adopted platforms, or another like DocBook, S1000D, TEI, SPFE, Markdown, or a totally custom-made platform with specific XML components for your niche?
Following that you’ll need a Pilot Study to test the limits and outcomes of the conversion. If your legacy documents have a lot of visual elements embedded into highly-designed page layouts, for example, the structured outcome may not be what you were expecting. This may give you an opportunity to tweak your style sheets and redesign your templates. During the pilot phase you may also find out that you have difficulty with some of the output formats. This is the time to correct such errors or find workaround solutions. Once the pilot project starts to generate the kind of outputs you are pleased with you can go into full production and scale up your production.
As Scott Abel says: “Don’t jump in [to structured authoring] without a clear business case, a repeatable strategy, and measurable goals” (http://thecontentwrangler.com/2006/07/30/10_dita_lessons_learned/).
Do your homework and ask all the above questions before making a commitment to structured authoring.
This is a long-term conversion project that requires significant investment of time, money, and human capital. It’s better to stay on the sidelines and watch where this particular documentation niche is going than investing heavily because “it’s the new sexy trend to follow” and suffer in the end.