By Julio J. Vazquez
Heretto guest blogger
Take a trip down memory lane with me. I promise that it won’t take long but I need to set the stage for you so you understand from where I’m coming. We’re going to jump into the Wayback Machine (patent pending) to a time before DITA. A time when as a technical writer, I was creating content for multiple products.
The challenge was difficult. We needed to support the products with few writers. The products were extremely similar. It made little to no sense to create multiple copies of files just to change the context slightly for each product. Things like labels, models, product names and numbers in many cases were the only things that changed. When we did an analysis of the source information, we discovered that less than half of the content was unique. How did we proceed? By filtering the content.
Originally we stored all the variable content in the base source files. This wasn’t too bad when looking at 2 or 3 products but as the number of products sharing the same content grew, it quickly became a nightmare. We couldn’t see what we were working on because we were distracted by the growing number of variables that were inline with the base content.
EXAMPLE: “[ABC Yogurt, DEF Yogurt, GHI Yogurt, JKL Yogurt, MNO Yogurt, PQR Yogurt, STU Yogurt, VWX Yogurt, YZA Yogurt] makes a great yogurt in various favors…”
This led us to the next step in the evolution: move the variations into a separate file and put placeholders for them in the base content. That way they didn’t clutter up the source and make it hard to read.
Along came DITA 0 (yes, I’ve been at this that long). It was relatively simple to take that model and move it over to the new architecture. Conceptually, little changed between the SGML tagging we were doing and DITA. We still put the variable content in a single file (all_products.dita) and then used a profile to filter out what didn’t belong in the current output stream.
EXAMPLE: <p><ph conref=”all_products.dita#topicid/productname”/> is great yogurt in various flavors.</p>
This is what all_products.dita would look like:
<ph id=”productname”><ph product=”ABC”> ABC Yogurt</ph><ph product=”DEF”>DEF Yogurt </ph><ph product=”GHI”>GHI Yogurt </ph></ph>
We then created a ditaval file that included the one product for this build and excluded the others, or defined a default for product that excluded undefined values that may not be the right thing to do for this document. Things got messier as we start adding more products and maintaining the ditaval file became more and more of a burden. We were doing more with less, but we knew things weren’t going to scale very well and that we were going to end up spending too much time managing the profiles.
Along came DITA 1.2 and the concept of keys. Keys use DITA Maps to manage the variable content (like product names) inside generic, reusable topics. In our example, every yogurt brand has its own set of maps that combine reusable topics into product-specific deliverables. A unique “warehouse” file maintained and stored with each map is the perfect place to define the context for those documents.
The reusable topics never change. They refer to variable content using a conkeyref:
<ph conkeyref=”product/prodname”/> makes great yogurt in various flavors.
The map for ABC Yogurt links to the warehouse file that defines each variable:
<keydef keys=”product” href=”ABC_product_terms.dita”/>
The warehouse file now contains this:
<ph id=”prodname”> ABC Yogurt</ph>
In my mind, this is a more elegant solution for creating multiple documents from a single set of files. Individual topics are more reusable because they never need to be updated when new products are added. The warehouse files that define the variables in each deliverable stay with it from creation to obsolescence, making them easy to find and maintain.
Sure I wind up with a few more files but I get myself out of the management problem of ditaval files that have to reflect the profile that fits the particular context for the document. No more having to figure out if I’ve covered all the cases in a single file that is becoming more difficult to analyze with each new product variant. No need to determine what the profile should be for contextual clues based on a document. I can reserve profiles for other applications that make more sense, like faceting content to meet the needs of audience, platform or product.
