Once And Only Once For Requirements Documents

(Originally on OnceAndOnlyOnce, RaySchneider wrote:)

OnceAndOnlyOnce is a definite must for requirements documents. Following this principle you won't ever have to reconcile many different versions for a requirement which have propagated all over the place. And its a good argument for hypertext too.

Also, it's just good human policy, too, since it cuts down on the severely mind-numbing, repetitive nature of document writing.

I'm not sure this is a good policy for the humans who read documents. For people, repetition is good (remember the say it three times rule?). Nothing is harder to understand than a document where every statement is referenced to other sections. Hypertext is just as problematic and you find yourself jumping all over and losing the original train of thought. Organize (and re-organize) your documents, but do not be afraid to repeat text if it adds to the clarity of the document. -- WayneMack

Agreeing with Wayne, when it comes to requirements and other human readable artifacts, the rule is a DuplicationRefactoringThreshold of 3. Still if you word it well once, it can be used verbatim elsewhere as needed. When I read a document that was prepared this way, I soon come to recognize a repeated passage and can choose to read it in detail or not, depending on whether I've assimilated it yet or not. -- WaldenMathews

I'm not convinced. At the very least, one of the occurrences should be labelled as the definitive one; then no problem in repeating the requirement somewhere else. Without that, the requirements always end up being worded/interpreted differently each time they appear; a fertile source of later disagreements. Multiple occurrences also make changing a requirement a pain - it's difficult to be really certain you've caught all occurrences. -- PaulHudson I guess it's a problem if the requirements document is in Word format, but if it's in LaTeX you can define it with a \newcommand (or possibly as an \input directive).

Well, what documents are stored in system that supports defining requirements once and only once, but representing them repeatedly wherever they need to appear. -- SteveJorgensen

Perhaps the DuplicationRefactoringThreshold depends on the audience. Technical people will probably be okay with a lower threshold than management or non-technical users.