Suite Level Operation

Keywords: FrameMaker, book, DITAMAP, oXygen, suite, DITA, XML, Samalander, Link-Fixer

Most DITA XML authoring tools operate on individual DITA files or DITAMAPs. FrameMaker's primary organizing feature is the "book". oXygen and other DITA authoring tools' primary organizing feature is the DITAMAP. In other words these tools operate at a document level.

But, as all technical writers know, this document focus is adequate for most writing but it is a disadvantage as soon as we have to deal with many titles, or worse, many titles maintained by many authors. There are in fact at least two levels of organization required in almost all writing projects:

  1. the individual title and
  2. the project, or suite, as whole including all writers and all titles.

Samalander modules generally operate at the both the individual document and the suite level.

Why is Suite Level Operation Important?

DITA XML makes suite level operations especially critical to productivity. The fact that we end up with many more files than in traditional writing systems means that even simple tasks can quickly become almost, and in some cases actually, impossible.

Checking cross-references is a good example of the problems we can run into. Suppose we have a DITA file with three cross-references to various points within that file and some to other files. Now, suppose a writer breaks up that file into three pieces, each with one of the cross-references.

Obviously the writer then has to redefine where each cross-reference points to. With three files and three cross-references, each cross-reference can now point to two other destinations. Mathematically that means the writer has to make 2 + 2 + 2 = 6 decisions to fix the cross-references.

Now suppose we have exactly the same case again but this time with one file being split into 5 pieces. Mathematically the number of decisions the writer has to make is now 4 + 4 + 4 + 4 + 4 = 20. Obviously manual mistakes are going to be easy to make.

Example: Link-Fixer Suite Level Operation

Samalander's XML DITA Link-Fixer is a good example of why suite level operation is important. Link-Fixer automatically scans the entire suite for link problems and collects possible fixes. Going back to our original one file split into three example, Link-Fixer will automatically find the closest match to the original cross-reference in the entire suite. It does this using three criteria:

  • the file name,
  • the element ID, and
  • the cross-reference text.

So, in our single file split into three example the file names have changed but if the author simply copied and pasted elements from the original file into the new files, Link-Fixer will match the ID and the cross-reference text. It then uses this information in the report as a possible fix for the broken cross-reference. Select the new link in the Link-Fixer report and re-run Link-Fixer to fix the cross-references.

Note that this Link-Fixer technique gets around one of the major problems with XML DITA: the likelihood of making manual errors. Because Link-Fixer has three criteria when detecting possible fixes, it will present you with one, or at most a few possible fixes for each of the broken cross-references, not 6, not 20. Better yet Link-Fixer allows you to place the new files anywhere under the suite root so you can split a file in Suite Root / Product Line / Product-1 / and put the pieces in Suite Root / Product Line / Common / and Link-Fixer will still find the possible match and make the correct suggestion.

Wherever possible, Samalander tools assume you are dealing with many information products simultaneously and tries to operate in a way that makes your work easier, faster, and more efficient.