Subscribe Now!

Plan Your DITA XML Output Strategy First

Diane-L-ThompsonDiane L Thompson

Unfortunately, even after you learn to author in DITA XML, after learning to create the format instructions, after finding a translation agency that treats your new topics the way they deserve, you are not done. No time for a victory lap. Time to engage your output strategy.

Even more unfortunately, if you have not done those things you ought to have done continuously throughout the process, your output strategy will be more of an output mess. You must plan for and begin your output strategy at the beginning.

Plan, plan, and then plan some more

Since you are using a Task, Concept, and Reference format, decide in advance which type of topics will be Concept and which will be Reference. This is not always clear or easy to distinguish. Are all your introductory paragraphs a Concept topic? How about explanatory sections that don’t have any tables or reference type information, are they concept or reference? Hash these details out with the entire team beforehand and make sure everyone is on the same page. Do not assume everyone thinks the same way. We definitely don’t.

Are the illustrators on board? Have they worked out a style for the callouts? Have you planned for maintenance instructions that are almost completely illustrations and how do you make these topics appear consistent with text topics? Are you using a standard resolution or will you have to use conditional text or another DITA device to provide one illustration for the PDF output and another for HTML output? Has anyone considered mobile device outputs?

When writing the online help topic for a sub window, for example a dialog box with window-level help, do you repeat the main window section or create a subset of information? How do you handle examples? Is someone in charge of reviewing the daily output for consistency of style? Is that person clear on what the styles should be? Design all these information types in advance of starting the project.

Since you are using topic-based authoring, you are going to have a lot of files. Have you determined how to keep track of all these files? Do you have a useful file naming convention or are you using a Content Management System? If you want to reuse a particular file, are you going to be able to find it? Have you worked out which information bits, such as Notes, Cautions, and Warnings, will be used repeatedly?

Meet early and often

Most projects involving more than a single writer have some sort of kick-off meeting to establish duties and schedules. Add philosophy of DITA to this meeting. Make sure everyone understands how DITA works, how to use topic-based authoring, and how to write using a minimalist style. Minimalism isn’t mandatory to this process but it is smart. Have follow-up meetings, maybe even daily, to make certain everyone is staying on track and keeping within the styles set for each part of the document or user interface instructions. Have the person who is monitoring styles bring up the issues from the previous day’s output.

Set up realistic and beneficial translation schedules

Set up a translation schedule at the first meeting and update the schedule constantly. This may be the most difficult adjustment for both your group and the translation agency. Translation agencies are used to receiving the bulk of files toward the end of the project with corrections and additions in the last couple of weeks or so.

Remember that one of the reasons you went to topic-based authoring is that you can send one set of topics for translation while you are writing the next set. Yes, changes happen over that time but, if you have set up a system to manage your topics, you can mark the topics that need updating, attach the information for the updates, and keep going on the current set of information. This way, you have a constant stream of topics going to the translation agency without sending the same topics over and over again. The savings you achieve with this approach comes from all your planning, from the consistency of style, and from only translating the bulk of your topics once and the rest not more than twice.

Plan your ditamaps in advance but be prepared to change

Okay, so maybe you aren’t using ditamaps but the same idea applies. Have a strong notion of the arrangement of your files in the online help TOC and the print document TOC. If they are the same, okay. However, more likely than not, your online documentation follows the structure of the user interface and the print document follows a pattern of daily activities. So, if you have your output structure planned in advance, you can start putting topics where they are going to go as you are writing them. And when you are using ditamaps, this is pretty darn easy.

The result

If you have executed all these preparations, your output is already clean, translated, and in the right place for conversion to html or print at the end of the project. You just need those last couple (or more) of topics that are in translation and you are good to go.

If you have not done this planning and preparation, you probably have partially-translated sets of topics that have been translated multiple times. You have reviewers pointing out that your topics are obviously written by different people. You know you have cautions and warning somewhere in all this but aren’t sure just where they are. You have sub windows with help in wildly differing styles. And worst case, even your major topics are not in a consistent style.

So with planning, your output strategy is a natural outcome of your initial vision. Without planning, your output strategy is complete chaos. This makes for an easy choice. Do your output planning first.

I very much enjoyed authoring in DITA XML but could never get anyone to seriously plan for the day we needed to produce output. When I left that company, I decided to research and find out what we should have done and this article is the result. You can find it and more in my writer’s blog The Technical Author. For some great resources, read over my Book Recommendations page.


Leave a Reply





You can use these HTML tags

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>