Monday, November 5, 2007
Converting Legacy Content
When we selected DITA as our DTD/application, we did so, in part, because our current styles are a close match for the DITA structure. There are some minor variations but we chose to shave off the stuff that didn't fit and consider specializing the DTD later, when we had a grip on what DITA is and what using it does to our process.
Because our products are part of a family, each generation building on features, functionality, and options developed and delivered in early generations, we are accustomed to borrowing from existing content and reshaping to fit the new product and any changes to our styles.
We also have a content guideline that provides a structure overview. This document does not delve into the structure in the same way a DTD does; the structure overview says, essentially, the following information, in the following order, appears in this kind of document. This structure varies, somewhat, with each product release; its purpose is to identify the full scope of our most comprehensive documents.
You can see that we're a very organized group of people. We're pretty cautious and we're definitely turtles in terms of change. Faced with the theory of the transition to DITA we felt some apprehension. We attended multiple seminars, webinars, and training classes. Everyone talked about DITA at a very high level; we could talk that talk, without ever having authored a DITA topic. We were hungry for details.
Eventually, we had to start. During the planning phase, we identified some elements that would allow us to select the best starting place, topic by topic, for the new DITA content. We developed these guidelines:
What it comes down to is this: writers pick the version of the topic that fits the situation. In some cases, we're taking topics from older manuals and updating the style because the flavor of the features is more like those earlier products. In other cases, we're taking topics from the most recent product release and modifying the content because the tone and depth is more appropriate even though the implementation of the feature is different.
We are taking advantage of the transition to set a new gold standard for our content. The entire team meets weekly. The team includes production people, writers, editors, and managers; all these people have a stake in the outcome. It's in meetings of this group that goals, like the topic selection guidelines, come out through discussion and exploration of ideas and information received.
The experience of converting a simple set of product manuals and producing output gave us a road map for discussion issues. As each phase of our workflow came and went we discovered issues we could not have forseen. One of the other outcomes of these meetings has to do with handling graphics. That issue is unresolved. We managed, with the pilot project, to duck tape something together (to meet a deadline rather than actually resolve the issue) and as our new product deadlines can be seen on the near horizon, we're about to tackle the whole image issue, for real. I think I may have to fall down and take a nap.
Because our products are part of a family, each generation building on features, functionality, and options developed and delivered in early generations, we are accustomed to borrowing from existing content and reshaping to fit the new product and any changes to our styles.
We also have a content guideline that provides a structure overview. This document does not delve into the structure in the same way a DTD does; the structure overview says, essentially, the following information, in the following order, appears in this kind of document. This structure varies, somewhat, with each product release; its purpose is to identify the full scope of our most comprehensive documents.
You can see that we're a very organized group of people. We're pretty cautious and we're definitely turtles in terms of change. Faced with the theory of the transition to DITA we felt some apprehension. We attended multiple seminars, webinars, and training classes. Everyone talked about DITA at a very high level; we could talk that talk, without ever having authored a DITA topic. We were hungry for details.
Eventually, we had to start. During the planning phase, we identified some elements that would allow us to select the best starting place, topic by topic, for the new DITA content. We developed these guidelines:
- If the content is already converted, use it (or at least start with it).
- Otherwise, choose content based on the following attributes:
- Which topic is the most recent?
- Which topic most closely follows current styles, conventions, and terminology? Something that is somewhat implied in the first attribute... more recently content is authored the more likely it is that it follows the current styles.
- Which topic requires the least amount of rework? This is simply a variation on the earlier attributes.
What it comes down to is this: writers pick the version of the topic that fits the situation. In some cases, we're taking topics from older manuals and updating the style because the flavor of the features is more like those earlier products. In other cases, we're taking topics from the most recent product release and modifying the content because the tone and depth is more appropriate even though the implementation of the feature is different.
We are taking advantage of the transition to set a new gold standard for our content. The entire team meets weekly. The team includes production people, writers, editors, and managers; all these people have a stake in the outcome. It's in meetings of this group that goals, like the topic selection guidelines, come out through discussion and exploration of ideas and information received.
The experience of converting a simple set of product manuals and producing output gave us a road map for discussion issues. As each phase of our workflow came and went we discovered issues we could not have forseen. One of the other outcomes of these meetings has to do with handling graphics. That issue is unresolved. We managed, with the pilot project, to duck tape something together (to meet a deadline rather than actually resolve the issue) and as our new product deadlines can be seen on the near horizon, we're about to tackle the whole image issue, for real. I think I may have to fall down and take a nap.
Labels: conversion, dita, styles
Subscribe to Posts [Atom]
