February 5, 2014
The NS Loop: A Story of Rediscovery
When I joined Excosoft in 2006, no one had told me about the NS Loop function. It had kind of been forgotten at Excosoft, or at least buried at the bottom of the toolbox. I happen to have a passion for reuse, and enjoy scouring the archives of technical documentation for those lesser known tools which can be reapplied to new challenges. The NS Loop was one of those rediscovered tools, and this is what I learned about it:
Back in 2005 our customer Wärtsilä, in Finland, had a special request. Manufacturers of ship engines for the marine industry, Wärtsilä had already been using our product Excosoft (formerly known as Skribenta) to produce their installation manuals, and now wanted to extend this use to include their product guides.
They were marketing a wide range of engine variants for a particular engine line, with one guide for the Wärtsilä 32 engines, another for the Wärtsilä 48 engines, and so on. These guides were organized into tables, which presented the data for each engine variant in columns. The PDF looked something like this:
The data for each engine type had originally resided exclusively in a Wärtsilä database. As part of the Excosoft customization at Wärtsilä, this data had been automatically transferred into Excosoft and saved as variableswithin recipes¹.
Dreading the time consuming task of editing each column’s cell by hand, and then filling them in with variables specific to each engine type, Wärtsilä asked us, "How can we automate this so that we don't have to create the tables manually?” Doing it manually would have obviously been both an extremely time consuming, and error prone process.
Developed by Excosoft’s founder and Chief Technical Officer, Jan Christian Herlitz, the tool that saved the day at Wärstilä is what is known as the NS Loop function.
The initials “N.S.” in NS Loop stand for Name Space. A “name-space” is an important concept in Excosoft, as its central purpose is to make variable names unique. The concept is common in programming languages like Java, and it is also evident in web addresses like www.excosoft.se.
Since each of Wärtsilä’s engines had its own name-space, (like engine1.weight, engine2.weight, etc.), applying the NS Loop was the perfect solution.
Putting the NS Loop into Practice
The following XML image illustrates the results of applying the NS Loop.
How was this achieved?
- The writer has surrounded the table with an NS-Loop wrapper
- The wrapper is given a title containing all name-spaces, (in this case: C_E1, C_E2, etc.)
- One “template column” in the table contains variables (see red text above) which do not have name-space
- When the guide is published the template column is duplicated for each name-space and all variables in the column are prefixed by the name-space
- The result is that each variable gets a unique name which is replaced by the value in the recipe
The list of name-spaces in the wrapper title can be replaced by a variable. By doing so the table is completely defined by the recipe. This, in essence, reflects one of the rules we technical writers always abide by:
Adding a new product variant should only affect the recipes - not the master files²!
Far Reaching Results
When it came to producing Wärtsilä’s product guides, the NS Loop truly saved the day. Excosoft was able to create the recipes automatically using other databases, and no manual work whatsoever was required. Even when a new engine variant is introduced in the future, all Wärtsilä will need to do is publish the guide again-- and all the tables will contain the new engine variant "auto-magically".
After my rediscovery of the NS Loop I realized how useful the tool could be for other customers. Our customer Wärtsilä isn’t the only one who gained from this experience. To this day, I continue to introduce the NS Loop into countless manuals, bringing increased ease and efficiency to our customers’ documentation procedures.
¹ Recipe: Applied to the Master File, allowing for the filtering or customization of data for the purpose of publishing one specific document.
² Master File: An unfiltered core file containing the text and structure used to publish a specific set of documents.
- Information Design