Sunday, November 4, 2007
Transition in Authoring
Because our products share features, we are changing how we assign our development effort.
Previously, as each product was released, an individual writer was given the responsibility of pulling together the information required to create or update the user documentation. In this scenario, writers become generalists and researchers. The research may lead them to borrowing content from other products and tweak it to fit.
The content was stored in section files that were pulled together into a book. When we sent content to translation, they had to process the entire section file to find the changes.
When translators got this content, they may end up having to treat any "cloned and owned" content as new, thereby losing any savings in the reuse.
Our DITA approach is far more collaborative. We're a bit nervous for this first major project. Each writer is responsible for a sections of content. We tried to make the assignments that fit each writers' skill sets and interests. As writers we are then responsible for writing all content that fits within those sections of content. We share the glossary.
We share the glossary because we list controls with a link to their definitions. We're using conrefs to manage this (an interim solution is to have tables in the controls reference topics until we can figure out how to replicate our current presentation). This approach has the added benefit of being able to reuse the definitions across products even if the control name varies, which it sometimes does.
This saves on translation costs.
As we develop content to support products, we write more generally, using the strategies of single-sourcing to ensure our content can be reused without change. The concept topics provide the best opportunity for this level of sharing. The reference topics are, generally, specific to the product, but the conrefs allow us to reuse the definitions, at the minimum. The task topics are where the the variations between products present themselves. We have no idea how much content we'll be able to share between products in the instructions. We have set out the following guidelines to help us with sharing:
Which brings me to the second part of our new authoring process: building documents for a product release.
We stuck with our earlier strategy of assigning a writer to a release but, in the new model, that writer is responsible for processing the content provided rather than creating and processing the content. They become the point person for a release; they push the document through our process, setting up and managing reviews, publishing the final content as a PDF or CHM, and notifying translation that a document is in the final state.
Previously, as each product was released, an individual writer was given the responsibility of pulling together the information required to create or update the user documentation. In this scenario, writers become generalists and researchers. The research may lead them to borrowing content from other products and tweak it to fit.
The content was stored in section files that were pulled together into a book. When we sent content to translation, they had to process the entire section file to find the changes.
When translators got this content, they may end up having to treat any "cloned and owned" content as new, thereby losing any savings in the reuse.
Our DITA approach is far more collaborative. We're a bit nervous for this first major project. Each writer is responsible for a sections of content. We tried to make the assignments that fit each writers' skill sets and interests. As writers we are then responsible for writing all content that fits within those sections of content. We share the glossary.
We share the glossary because we list controls with a link to their definitions. We're using conrefs to manage this (an interim solution is to have tables in the controls reference topics until we can figure out how to replicate our current presentation). This approach has the added benefit of being able to reuse the definitions across products even if the control name varies, which it sometimes does.
This saves on translation costs.
As we develop content to support products, we write more generally, using the strategies of single-sourcing to ensure our content can be reused without change. The concept topics provide the best opportunity for this level of sharing. The reference topics are, generally, specific to the product, but the conrefs allow us to reuse the definitions, at the minimum. The task topics are where the the variations between products present themselves. We have no idea how much content we'll be able to share between products in the instructions. We have set out the following guidelines to help us with sharing:
- Instructions are tagged using the cmd and info elements.
This means we can apply conditions to either part of the step. - The point at which a shared topic is broken out into separate versions for each product is up to the writer responsible for the topic.
This allows us to explore the break point and gain experience. - Writers tag the topics and the section maps so that when a product map is used to generate a document only the content appropriate for that release appears.
Which brings me to the second part of our new authoring process: building documents for a product release.
We stuck with our earlier strategy of assigning a writer to a release but, in the new model, that writer is responsible for processing the content provided rather than creating and processing the content. They become the point person for a release; they push the document through our process, setting up and managing reviews, publishing the final content as a PDF or CHM, and notifying translation that a document is in the final state.
Labels: authoring, dita, user documentation
Subscribe to Posts [Atom]
