How often do you see the same piece of information documented in 2 places? I am used to seeing requirements information copied into design documents; whole sets of requirements being copied into a test repository and diagrams copied from one document to another. Unless you employ a strict change management control system that includes a traceability scheme, this sort of practice is going to prove expensive, for 2 main reasons:
- The work of maintaining information is being done twice.
- More expensively, if one artifact changes and the other doesn’t, how do we know which is correct? [1]
Employing an automatic update scheme, a traceability scheme which shows when something has changed or a strict configuration management scheme which prevents artifacts from being changed, will go some way to solving the duplication problems, but again they are expensive.
Rather than spending time and money in trying to control duplication; I recommend, ‘Don’t Do It’. Here are some schemes that can be used to prevent duplication:
- Put the information in a central repository and reference it with hyperlinks.
- If you must have the information displayed in two separate places, use Object Links and Embedding (OLE). Extract the information from both artifacts, place it in its own document and embed the document as an OLE.
- Use document generation tools, such as SoDA, to insert duplicated information into your documents.
- Ask yourself the question; ‘Do I need to put this information here?’ Or, ‘Can I reference the same information, located somewhere else?’
Do not copy, either use a link or make a reference if you absolutely must have it here.
[1] The worst example of this was on a contract where the test team did not like the way the developer’s document repository was organized, so they copied the developer’s documents into their own repository. The wrong tests were consistently being executed against the code.
Editor's Note: Check out the list of all related best practices.