You are viewing paulmck

Finding bugs in documentation

Finding bugs in code may be hard, but at least the compiler helps you, and you can also write torture tests.

Finding bugs in documentation is another animal altogether. There are spell-checkers and rudimentary grammar checkers, but nothing to find outright bugs. Therefore, bugs in documentation can persist for a very long time. A case in point is K. Prasad's locating an embarrassing and long-standing bug (since fixed) in the original What Is RCU documentation, where a list_del() should have been a list_del_rcu().

So what is to be done?

Part of the reason that this bug persisted for so long is that this documentation has been replaced, for example, by the Linux Weekly News three-part series (What is RCU Fundamentally, What is RCU's Usage, and What is RCU's API?). Therefore, fewer people would be reading the erroneous documentation, thus fewer people would find the problem and report it.

Still, debugging documentation remains an interesting unsolved challenge.