: 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?

Vote Up Vote Down

The more your documentation is aimed at people reading it like a book the less you should repeat yourself. The more your documentation is a look at this one page read it put it away the more you should repeat yourself.

The most concrete example I can think of are aviation emergency checklists. No Co-Pilot is ever required to look anywhere else after he opened the correct check list. Everything is on that one page. Even if it's a step that is on half the pages (think inform tower), if it's deemed important enough to be there it's on every check list.

Since you apparently use automated documentation I'd say few repetitions in the user training guide but repeat yourself a lot in the emergency recovery runbook.

(0)

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)