DRY Documentation…

DRY – Don’t Repeat Yourself – is it relevant for documentation? I recently saw this comment on a forum…

I’m not sure how useful it is to remove duplication [from the documentation pages]. It’s not code…

IMHO, duplication in documentation is a couple orders of magnitude worse than duplication in code (and duplication in code is bad) because bad documentation has the power to waste more people’s time.

With code, a single (knowledgeable) developer must take the time to read through the duplicated code to look for subtle differences.

But with documentation, every reader – perhaps hundreds of far less knowledgeable people – must mentally diff the two pages looking for common threads/important items/gotcha’s to try to be sure that they will succeed.

For example, these two documentation pages describe [some procedure…], and each describes an substantially different procedure. I often find the differing explanations so difficult to reconcile that I simply give up (or maybe resolve to come back some day), rather than bricking my router/leaving it inoperable/etc.

So, for common tasks, I believe it is always better to have a single well-curated page that correctly and concisely describes the procedure, instead of having multiple people write their own incomplete, or marginally correct procedure.

Leave a Reply