We regularly write about variant management in this blog, but we have yet talked about variants in the project tree. However, our ST4 Component Content Management System has a special tool for this very purpose: the project configurator. At the touch of a button, it creates an ST4 project, a bit like a 3D printer, based on the information it is provided with. Once you use it, you will no longer want to be without it. That also applies to the Danish company, SKOV; a complete provider of farm and climate management equipment, which has been working with ST4 since 2017 and which gave a presentation on how they use the project configurator at the SCHEMA conference.
Generally speaking, ST4 projects contain the publication structures for target documents. A project is created manually for this before a technical writer assigns content nodes to the project from the information pool. There are three possible ways here to create project variants:
However, the technical writer must manually reference the right nodes in the project precisely for all these options. It's a little like Michelangelo's David: everything that does not belong is removed. And that is the standard approach that generally works very well. However, if more and more variants for products and documents come along, manual configuration of projects simply becomes too slow.
Before SKOV implemented ST4 in 2017, document variants were still created with Word. Efficiency has been increased, particularly when it came to repetitive tasks, such as updating documentation in parallel with the development process. The introduction of ST4 has thus resulted in radical positive changes in SKOV's technical documentation, which have optimised document standards as well as internal processes.
The project configurator played a huge part in this. Editors at SKOV do not configure projects for the various variants themselves; they get the project configurator to do it. The project configurator acts like a magnet, dragging the nodes that are relevant to the project, thus replacing the manual step of referencing nodes. What's more, in addition to the referencing, it also creates a project.
Right from the start, we were on hand to help SKOV's technical writers to use the project configurator. The document and project landscape at SKOV is structured as follows:
Reused nodes are highlighted in colour.
Most of the information nodes are reused in various different documents. A node with the content “Product description" can thus be found in at least 5 different documents. The structure of the documents themselves also differs considerably. Manually creating a project thus poses the challenge of dragging the right nodes into the right projects and not to overlook any relevant nodes.
However, what is needed now to enable SKOV to work effectively with the project configurator? What requirements need to be fulfilled?
If you start by thinking backwards from the end, in other words, from the finished project with the necessary filters assigned, everything becomes clear. If the project is not created manually, it needs to be made clear on the actual information node why it belongs to this project and not to another one. This could be the document type (e.g. comprehensive user manual vs. maintenance documents), or the product (components vs. module vs. machine; service specification of a piece of software vs. window help). The project configurator therefore needs distinctive features that show it that a certain node is required in both the user manual and service manual and applies for the whole machine.
The following three preconditions therefore need to be established in order to use the project configurator:
Clear node classes
Node classes can be used in accordance with the SCHEMA concept (guide, maintenance, operation, etc.), for example. For the highest level, SKOV only uses universal text nodes.
“Everything starts with the taxonomies"
To use the project configurator effectively, the technical writers at SKOV have created a concept for their taxonomies and have decided on three separate taxonomies: product, information and document type.
The product taxonomy is the leading taxonomy here; the other taxonomies are dependent upon it. A leading taxonomy is always required to be able to distinguish which meta datum determines the subsequent meta data. For the project configurator, SKOV also uses the information taxonomy. The third taxonomy of document type is only used when creating the layout.
Structuring documents with templates and placeholders
SKOV then set up templates to reflect the structure of their documents. However, the templates do not consist of information nodes with content; they consist of placeholder nodes. These are “search nodes" that represent all nodes that should be in their place in the project. When creating a placeholder, you specify the criteria according to which the nodes are collated - in other words, what is drawn in like a magnet using the placeholder and included in the project:
At SKOV, a template for the “Technical information" document for two products looks like this:
SKOV uses one template for each document. As this template and the placeholders it contains can constantly be amended, it can also be handled flexibly in future.
And now comes the exciting part: the project configurator in use.
The project configurator begins the search using the templates and the incorporated placeholders with meta data. It selects the placeholder nodes and collates the content nodes in which the respective characteristics are stored. The overview shows which and how many nodes for each taxonomy and information type have been found, allowing you to see at a glance whether any content is missing.
You can even create new nodes directly here, which you can then fill with content. These nodes will then have the right characteristics for the project. This is an important feature for the technical writers at SKOV, reducing the number of work steps and minimising the risk of assigning taxonomies incorrectly.
Click on “Create project" and the project configurator creates the project. The title of the project is the same as the template and already contains the variant filters used. This is clear from comparing the template with the project configured from it at SKOV. The placeholders (title in English) are populated with the relevant content nodes. The placeholder “Product description" finds the “Produktbeskrivelse [DOL 63X]" node with the taxonomies recorded for the project:
For SKOV, the greatest benefit of the project configurator is the project overviews: for each accessory, there is an individual node that is added to the respective project by the project configurator as a result of the taxonomy. This would be a huge manual workload, as many products have the same accessories and the technical writer would have to assign each accessory individually to each variant.
By the next software update at the latest, the huge benefits of the project configurator will become apparent at SKOV. At that point, technical writers will be able to create documentation for all software variants and languages in a single workflow.
The project configurator is an interesting tool wherever there is a need for well-designed taxonomies and clear use of information types. As in the case of SKOV, a whole new level of, and approach to, project creation will be achieved. Manual project creation will especially reach its limits if data is in a cloud (the key word here being iiRDS) and compiled centrally to form projects.
Kirsten Müller Nielsen
Master in History and Religion. Researcher at an industrial museum. Major career change and working with technical documentation since 2002 - mainly SW translation and documentation. Since 2016 Documentation Manager in the R&D department at SKOV A/S.
Enjoying the challenge of developing our team, work processes and customer focus – and implementing ST4 (Oct17). Using lean methods for continuously improvement. Certified scrum master and auditor (ISO9001).
Moderatorin Kerstin Berke und Marketingspezialist Philipp Eng sind das Duo vor und hinter dem Mikro der „Doku-Lounge“…