: Re: Does DRY (Don't Repeat Yourself) Apply to Documentation? In programming, it's usually accepted that DRY code is better code in most situations. Does this principle also apply to documentation?

@Shanna875

Vote Up Vote Down

Yes it does.

You will be writing your code based upon a Software Requirements Specification. This will contain a series of numbered clauses in the form:

If x happens do y

These clauses will not repeat themselves as they must be uniquely testable and auditable. DRY most definitely applies in this part of the documentation.

So in your code documentation, you expect to see statements along the lines of:

Function x() satisfies requirement 123.

This gives you a one-to-one verifiable trace that the software has been written to do what it should do.

Any repetition, e.g.

Function x() satisfies requirement 123 but needs function y() which
satisfies requirement 234.

leads to the possibility of confusion and later disagreement as to whether the software passes verification and validation. Also, many automated V&V tools will baulk at multiple references.

Obviously dependencies must be documented, but repetition should be avoided if possible.

The User Manual will, in many cases, refer to the Requirements Specification. Indeed in some cases, the Requirements Specification is the User Manual. The requirements are written from the point of view of the end user and the Requirements Specification is also used for training. This can be a contractual requirement in my experience. There too you will need to reduce the number of repetitions if possible.

(0)

Login to post a comment!