June 2016
By Jang Graat

Image: stokkete/123rf.com

Jang F.M. Graat is a philosopher and self-taught programmer with almost three decades of experience in technical communication. He lives in Amsterdam and recently joined the US-based company The Content Era.




Reviewing the review process

How "live XML documents" revolutionize a rusty, ancient paradigm.

The disclaimer fallacy

"Although the utmost care was taken in putting together this publication, human error is always possible. We do not accept any liability for inaccuracies or omissions in the article and cannot be held responsible for any damages resulting from such errors."

Does this statement ring a bell? You will find this type of disclaimer in almost every machine manual on this planet. It is so common that most people never even notice it. But if you really think about it, this all-too-common disclaimer points at a serious problem that most companies choose to ignore rather than solve.

As a self-employed technical author, I have been arguing against this disclaimer from the very start, telling my customers that 1) they are offending my credibility as a professional, 2) the disclaimer will never hold up in a court of law and 3) it is very bad marketing, as the statement basically tells customers to not trust the manual or the product, for that matter.

What if the first paragraph in a machine manual read something like this instead:

"The utmost care was taken in putting together this publication and we believe it to be complete and correct. Therefore, we take full responsibility for any errors that may have been overlooked, and will reimburse any damage that may result from such errors."

Would you be more inclined to buy and use the product? I am taking a wild guess that your answer will be "Yes".

So why are all those companies still using a disclaimer that sabotages their marketing efforts and hurts their credibility? The answer is that their reviewing process is fundamentally broken. That process, and how to fix it, is the subject of this article.

What is wrong with reviewing?

Ever since my early years in technical authoring, I have been stunned by the slowness and awkwardness of the review process. In those early years, common practice was to print the content, hand the paper copies to your subject matter experts (SMEs), chase them for weeks to get their notes, chase them for another week to get them to decipher their horrible handwriting or cryptic notes, make the changes in your source documents and possibly restart the entire cycle once more to get everything right.

And, of course, the above scenario only worked for a small minority of my customers. In most cases, the SMEs were not even allotted any review time, as they had much more important work to do and were always running late on their current projects. Handing them a printed manual for review was fundamentally the same as throwing the manual into the garbage and ticking the box "review done".

Later, much later, PDF comments were introduced and things improved – but just a little. Instead of having to decipher notes scribbled on the margin, I received PDF comments, from which I could sometimes even copy/paste the requested changes or additions into the source documents. Still, comments were often placed haphazardly across the pages and a lot of searching was involved to figure out where all the requested changes were necessary.

Also, many SMEs did not have a clue how to handle the PDF commenting features and scribbled their notes on paper anyway. Asking them to provide the notes electronically sometimes resulted in a huge file containing a scanned image of a printed PDF with notes scribbled on the margins. I am not making this up. In fact, this exact scenario happened to me only last year. I politely told the reviewer to redo the comments in a PDF reader or get someone else to type them up before sending them back to me.

But the opposite also poses a problem. I did speak to several authors who have been swamped with comments from all their reviewers, creating an intricate puzzle of comments to be figured out, as every reviewer had been commenting on almost every part of the content, each in their own wording and from their own background. Although at first sight you might think this is wonderful and shows true engagement with the documentation by the entire company, it is not the most efficient way of running a business.

Adding the option to reply to reviewers’ comments (and allow reviewers to comment on each other’s comments) only adds to the complexity of the author’s task to get it all right in the end. It also increases the work pressure on reviewers, as an entire discussion might evolve, all stored in the source document, which becomes more and more of a puzzle with each cycle.

These two extremes on the review spectrum (from zero response to being swamped with comments) indicate that today’s reviewing tools are inadequate. It is not the subject matter expert’s fault that reviewing tools are clumsy, slow, or not specific enough. This insight inspired me to develop a new approach to reviewing, which is explained in the remainder of this article.

Reviewing in the browser

The first step in redesigning the review process tackles the clumsiness of most available review tools. It is based on the change in focus of most technical documentation: Nowadays documentation is published on the Web rather than as a PDF. And even if a PDF is still produced, it is created from the same sources that result in an online version of the same piece of content.

Having content available online opens possibilities that we did not have in PDF-based reviewing. One of those is based on a standard feature of HTML5 that most web developers do not even know about. By setting the "contenteditable" attribute of a paragraph to "yes", you turn your browser into a simple text editor. And the good news is that it works on any device, as long as the browser is modern enough to support HTML5. Any computer, tablet or smartphone will do.

The best thing about this method is that the SMEs do not need to learn the use of a review tool. They do not even need to download or install any software (many users do not have sufficient privileges to do so, anyway). Just open the page in the browser and enter the changes right there. It also means that the information to be reviewed is shown in context, as it appears in the exact same way that it would to a customer.

The tricky part is to catch these changes and feed them back to the server. This requires a small piece of Javascript and an equally small piece of code on the server. Not much more complicated than creating a form and processing the entries when the user hits the "Submit" button. Of course, you have to know where the changes were made, but that’s not rocket science either.

By the way, I am consciously ignoring the commenting features that can easily be added to this setup. Commenting via a feedback button is easy. Editing content in context is harder to do and therefore more interesting to write about. In a true review process, I would of course add the commenting feature to the editing options.

Precision reviewing

I can already hear your objection: "But wait, this does not solve the issue of swamping the author with comments." And of course you are right. Making reviewing so much easier for all subject matter experts will in fact increase the danger of getting bombarded with edits. This leads me to the true meaning of the subtitle for my article, about having XML on the server.

In my article "Faster than agile – live XML documents", published in tcworld magazine in November 2015, I explained a new approach to online publishing, which postpones the transformation from the XML source to the HTML5 output to the moment when a page is requested from the web server. This technique is the key to what I refer to as "precision reviewing".

As I explained in that article, we know a lot about the person who is viewing the page from the parameters that accompany every http request. And if we add a login shell around our review content, we know even more. This knowledge can be used as a parameter in the transformation, so that only specific portions of the content become editable in the browser. Which portions are to be editable for which SME can easily be defined in attributes that are set in the XML source itself.

This optimizes the review process greatly. The author sets attributes in the XML source, specifying which parts of the content are to be reviewed by each subject matter expert. For instance: The engineer is authorized to change measurements and other reference materials, marketing staff can only touch the introduction and the systems designer is allowed to change procedural steps.

The XML source, enriched with the review-related attributes, is saved directly on the web server. Note that this would normally be a special staging server, which is only accessible from the intranet or via a login. In both cases, the server knows who is requesting the page and passes that information to the transformation script. The script uses the information to only make those paragraphs editable that match the review settings in the XML attributes.

With this type of tooling, having multiple SMEs review the same content at the same time is not a problem anymore, as each expert can only edit sections that he is authorized to edit. Similar techniques can be used to show comment buttons, allowing the expert to make more elaborate comments or to forward rationales for changes to the author.

Processing the review edits

The final piece of the puzzle is feeding the edits back to the author. This will not come as a big surprise: As the XML sources are available on the server, a fairly simple method can be used to integrate the changed content into those sources. The exact format in which they are integrated depends on the XML standard that is being used.

This is where the true power of XSLT becomes clearly visible. We are not only using it to transform XML to HTML5 for the browser, but also to transform one type of XML (the standard that is used to store all content and incorporate all edits on the server) to another variation of XML (the standard that is used by the authors in their particular authoring software tools). This is especially useful when it comes to reviewing, as each authoring software uses its own method for representing tracked changes and comments. Converting review edits into tracked changes of the type that can be handled by a particular authoring tool is a piece of cake for XSLT.

And there are even more advanced options. If very experienced engineers review particular pieces of content, why would these changes not be accepted immediately, instead of passing through the technical author’s desk? The author probably needs to confirm the changes with the exact same engineer who made the changes in the first place. On the other hand, if a novice engineer makes the same change to the same piece of content, it might be a good idea to run it by the author, just to make sure no mistakes were made. These differences in handling browser-based edits can easily be modeled on the server, using the same login information that was required to make the right portion of content reviewable in the first place.

A new era for reviewing is here

The basic approach of placing XML sources on the server and postponing the transformation to HTML5 to the moment the material is requested has not only given us the chance to be "faster than agile". In combination with the "contenteditable" feature of HTML5, it also allows us to create a revolutionary approach to a review process that was fundamentally broken.

Instead of producing yet another review software, we brought down the level of required reviewing skills to editing a piece of text in your preferred browser. At the same time, the author receives much more control over the review process by assigning precise review tasks to people in various business domains.

Note that having the XML on the server does not mean that PDF creation has left the stage completely. In many cases, the review process will run on a staging server, from which the sources are passed to the publicly available server when the review is done and the product is released. At that time, those same sources can also be used to create the PDFs for release. In another situation, on-demand PDF creation might be added to the server’s capabilities.

With this new review process readily available, no company should ever again feel the need to put useless disclaimers on the first page of their manuals.