October 16, 2014
Managing Variation in Reused Content with Configuration and Automation
It’s time to wrap up this series on Managing Variation in Reused Content. We have investigated some basic techniques in part 1 and part 2. In part 3, I made the case that heavily customized documentation is often best handled in separate version branches. Before concluding, let’s take a quick look at two advanced topics: configuration, and automation.
The techniques we have discussed in this series rely upon the separation of content from configuration. This means that the content makes use of generic variables, with each individual publication variant defining the values for those variables. The established values make up the configuration, which is an important asset since everything that is specific to the given variant is assembled in a form that is easy to survey and understand.
Configurations can be organized in different ways, depending on the situation. Sometimes it makes sense to collect the different aspects of a configuration separately. For example, some aspects of a given configuration might depend on which market a product is sold on, while other aspects depend on which add-on features the customer has purchased. In this case it makes sense to store the market configuration separately from the customer choice configuration; thus enabling the market configurations to be reused independently of the customer.
Another way to organize a configuration is to qualify variable names with a prefix indicating which domain or function they apply to. For instance, a variable that specifies whether or not a washing machine has an energy saving Eco Program could be called “Has Eco Program”. However, more can be achieved by calling it “Programs.Eco.IsAvailable”. In this case the variable is qualified twice: first with “Program,” which tells us that this variable has something to do with programs, and secondly with “Eco,” which tells us that it relates to the Eco Program specifically. The final part, “IsAvailable,” can only be understood in relation to the qualifications. In Skribenta, the qualification part of the variable name (“Programs.Eco”) is called a namespace. Namespaces organize variables in a tree-like hierarchy.
Many companies already have a system for managing product configuration, such as a PDM system or configuration management tool. Maintaining the same information in several different places is always a bad idea, so the only way to go in these cases is to integrate the two systems so that a variables’ values are automatically loaded into the CCMS. A mapping table may be required to get the variables organized in a way that makes sense for technical writers.
A lot of the production process for documentation can be automated by simply switching over to an XML-based production system. What I’m referring to here is automated content creation. The Eco Program in our example is just one of the many programs available in various washing machine models. Each program has its own namespace inside the top level “Programs” namespace. This makes it possible for the system to automatically recognize which programs there are, and to generate content based on that information.
One specific example of how this can be done in Skribenta is the “NS Loop” which is used to automate production of content in tables. You can read more about the “NS Loop” here.
One idea, (which we have not built into our CCMS yet), is to allow for the scripting of content. A simple script language could be used and applied during the publishing process. It would access the XML source content as well as the configuration. Add to that the ability to access external data sources, such as configuration databases or PDM systems. Using some utility functions for inserting content, it would provide complete freedom to automate content in any way imaginable.
Suppose we want to create one section for each program that is available in a configuration. The section should contain some data about the program. All the data is in the configuration in the “Programs” namespace, so it should be possible to automate the content. This is getting quite technical and requires some programming skills, but the script could look something like this:
This very simplified example would iterate across all programs; and for every program available in the current configuration, a section would be added with the program name as the title. Inside the section, two paragraphs would be added: one for the washing temperature, and one for energy consumption. All lead texts would be stored in a separate namespace — “Localize” — to make sure that they are correctly localized in each publication.
If you have any questions about managing variation in reused content which I have not addressed in this series, feel free to include them in the comment section below. If it’s a really good question, I might even write a blog post about it!
- Information Design