Maintaining consistency over documents

Question

In the company that I work for we have documents covering system requirements, standards, user acceptance, etc. each of these are maintained manually. If a change to the requirements is made then it has to be made in a couple of places, user acceptance criteria needs to be added associated with this requirement etc. etc.

As this is done manually there have been occasions where the person updating the documents have updated it in the main document but neglected to update it in another. Which while have been caught prior to being sent to the user so far would be quite embarrassing if the user found this before we did.

So I was wondering whether anyone knows if there is any automated way of dealing with this issue then I would be greatful to know.

Answer 1

I am not a huge fan of automation without some level of human intervention.

• It is too likely that the business rules in your automation logic will be imperfect and will fail to catch what a human could catch intuitively.
• It is too likely that your team will get "dumbed down" if there is an overreliance on automated processes, in the same way that reliance on a GPS can lead people to literally go down the wrong road when common sense dictates otherwise.

Per Mark's answer, develop an end-to-end process for manual effort and then figure out what can be automated. At a minimum you will still need manual intervention as part of an auditing process.

Per DeerHunter cross-referencing should be used if a human were to do the work and can support your auditing. If you are going the paper route all it takes is a table in the back of each doc listing what other docs it cites, and which docs cite it. If you are doing things more electronically you could get away with a simple Access DB or Excel spreadsheet, nothing fancy.

Answer 2

Difficult problem, and I doubt there will be any simple answers. I would suggest a corrollary's to CodeGnome's law. First, decide what the process is - how do you make sure that a change is applied in all the appropriate places. Once you have that, figure out how to automate it. Automation is a tool not a solution.

In your shoes, I'd apply change control first. When a change has to be applied to a document, BEFORE it is applied have the author run the change past a group of stakeholders who will review whether that change has any other implications, has adequate User Acceptance Test, needs to be incorporated elsewhere, etc. The first dozen times through the process will be cumbersome, but pretty rapidly people learn. Once people have learned/evolved informal procedures look for opportunities to automate the routine. At this point as @Deer Hunter says, you can concentrate on the margin cases requiring human attention.

Answer 3

TL;DR

If you can't do it by hand, then you can't automate it. Automation is a tool to increase consistency, but it is not in itself a substitute for a well-defined process or process control.

A Whirlwind Tour of Potential Solutions

There are many technical answers to a question like yours. Some include:

• macro languages like m4
• single-source document markup languages like AsciiDoc
• templating solutions
• integration of sub-documents
• database normalization for use with document merges
• commercial systems like Rational DOORS
• home-brewed scripts using sed, AWK, Perl, Python, or Ruby for find-and-replace

However, all of them miss the real point: when you talk about validating quality and consistency, you're talking about controls.

A Quick Overview of Controls

Controls come in various types:

• Physical controls
• Technical controls
• Administrative controls

and with varying objectives:

• Preventive controls
• Detective controls
• Corrective controls

You are currently implementing a manual process with at least some detective and corrective controls. If you didn't have any controls in place, you would not have detected or corrected your errors before documents were sent out. Q.E.D.

Document and Evaluate Your Process

You have a process; document that down to the procedural level. Your process has controls; document them, too.

Once you fully understand your current process, measure the effectiveness and costs of both your process and your controls. Perhaps you need a better process, or maybe an appropriate technical or administrative control will become obvious once you start analyzing your process more closely. Then again, maybe all the right pieces are already in place, and you just need to make sure the process or controls are actually operating as designed.

Administrative Controls Are Usually Easiest

In my personal experience, administrative controls are usually the easiest to implement, although (by definition) they are not automated. For example:

1. Institute a formal document review process.
2. Document a repeatable procedure for each set of changes made within the process.
3. Implement a checklist of things to validate.
4. Require sign-offs for each administrative control stage.

The automation you use, if any, should be selected based on how well it integrates with your defined process, and whether the automated controls have fewer false positives or false negatives than your manual controls. An unreliable automation is worse than no automation at all.

Answer 4

This is a very common problem across many types of documents. The solution used in Technical Communications industry is referred to as "single-sourcing," which is the ability to write something once and then reuse it by reference in the various places where it is relevant.

There are many commercial products to support the creation of single-source (also called component-based) content. As with most technologies the range of solutions spans from open source to very expensive. Many of the solutions require a Component Content Management System (CCMS) but it is not an absolute requirement. Most of the solutions utilize XML as a markup language for producing content however it is increasingly popular to hide the XML from authors in either a browser or word-like editor.

The biggest concern for someone who wants to single-source content for project documentation is the sheer amount of information and number of products dedicated to this subject. If you have any contacts with full-time technical writers you might want to see if they are single-sourcing their content and could help you to get started. You could also check to see if you have a local chapter of the STC (Society for Technical Communication). The members are generally very helpful although not all of them are single-sourcing content.