Software Documentation – Meaning of the Quote: ‘A Bug in the Code is Worth Two in the Documentation’

documentationsoftware

As I boot up Eclipse for C++ with the "Darkest Dark Theme with DevStyle" installed, it spits out quotes–one per day. Yesterday's was:

A bug in the code is worth two in the documentation.

Talk about ambiguous! What does that mean?

A Google search for it (and this one too) shows it is a rather popular quote.

Possible meanings:

  1. (what I'd like it to mean, but what it isn't really saying well in the least): documentation is so important that it takes 2 bugs in the documentation to equal 1 bug in the code, so even if documentation has bugs (meaning: errors, or is out-of-date), it's still better to have the documentation than not to have it.
  2. A single bug fix in the code creates 2 bugs in the documentation unless you update the documentation in 2 places.
    1. Ramifications and implications: don't have documentation–it's too hard to keep up with code changes and bug fixes in the code.
  3. 1 work unit of effort from a developer is enough to fix 1 code bug or 2 documentation bugs.
    1. Ramifications and implications: unknown
  4. 1 work unit of effort from a developer is enough to fix 1 documentation bug or 2 code bugs.
    1. Ramifications and implications: unknown
  5. It's better to have bugs (errors) in the documentation than bugs in the code.
  6. It's better to have bugs in the code than bugs (errors) in the documentation.

Best Answer

It appears to be a twist on "A bird in the hand is worth two in the bush" - meaning you should hold on what you have rather than risk losing it for something more. That sentiment can make sense in software engineering, but I don't see how the modification makes sense when you try to parse it as a derivation:

Better to hang on to a bug in the code, than risk losing it to introduce two in the documentation

The original meaning clearly makes no sense. You can twist it in plenty of ways:

  • Bugs in code are about twice as bad as bugs in documentation
  • Better to keep a code bug that is well described in the docs, than to fix it and have outdated docs
  • Bugs in the code take twice the effort to fix compared to bugs in documentation
  • Etc.

But I see no reason to prefer any of these meanings, and without context or attribution I can only insert my own values.

Most matches are on sites relating to "computing humor", along other quotes such as "The definition of an upgrade: Taking old bugs out and putting new bugs in". Given that, plus the open-ended meaning, I think it is simply a funny substitution, and that we shouldn't try to read into it more than that.

Related Topic