Publication Integrity

by Robin Shobbrook

In this short series of blogs I’m going to consider the subject of Publication Integrity in the field of technical information and technical publishing. Let’s start off with the issues of document history, provenance and authority.

Part 1

History and Provenance

OK, so imagine you have produced a well structured, well laid-out, fully informative, unambiguous set of technical documentation: user guides, specifications, maintenance manuals, procedures and training material. You and your team have put in a lot of effort into creating, fine tuning and updating it all.

Now imagine that a regulator wants to audit your documents and asks you to show the provenance of some of the content: -

Or perhaps your quality or safety manager asks the same questions. Worse still, you’re involved in a legal dispute and the accuracy and clarity of your documentation is brought into question.

In highly regulated, safety critical and potentially litigious areas of industry and commerce, these are all increasingly relevant questions being asked. So how do you provide the answers?

One way is to manually record all activity, including file names and locations, dates etc. in a spreadsheet and set up procedures for keeping it up to date. Doing it this way is obviously difficult to enforce and is open to errors, omissions and resultant problems in traceability. It’s probably OK for a very small number of simple documents maintained by one or two reliable people - but beyond that, it’s not really a viable proposition.

There are many proprietary content management systems which claim to help do the job, but most are cumbersome to use and are aimed at handling whole documents rather than components of documents such as individual sections, paragraphs, illustrations etc.

Some, such as Koala’s Modulux Component Content Management System (CCMS) are purpose built for the job and so provide the best solution for ‘modular’ structured documentation and preferred (and often mandated) today. History and provenance (data about the data) can even be incorporated into the actual content files themselves so that each ‘chunk’ of content text can be interrogated independently to show its origins. So it’s all fully traceable and auditable.


Alongside History and Provenience we also need to consider ‘Authority’. This can be broken down into three aspects:

  1. Who is authorised to view, create, edit or even delete each component part of each document.
  2. Who is authorised or assigned to review and suggest changes or enhancements to documents or sections of documents
  3. Who authorises the release of each version of each document for publication.

Once again, it is vital to record this information accurately and a manual approach is not to be recommended.

Aspects 1 and 2 above are usually best left to the CCMS. The system administrator should be able to set up a database of authorised users, each with different privilege and access ‘profiles’. The usual practice is to have individual document ‘owners’ who can assign and manage ‘groups’ of subject matter experts (SMEs) to edit and review specific documents and parts of documents. This is ideal for team working.

The CCMS should record each time users check-out, edit and check-in files, so this data can be used to provide the content’s provenance and history, as mentioned above.

The third aspect – “who authorises the releases” - can also be handled, in part, by the CCMS. Once again, it’s important to record this information and, if possible, embed it in the document files themselves.

See Part 2 of this short series, for a more detailed discussion on content management.
Part 2 also covers how your document publishing can be made more resilient in the areas of recovery after technical issues or when previous versions of documents need to be recovered and reconstructed.

 Back to top
Back to BLOG page ...







Robin Shobbrook is Test and Quality Manager at Koala