Happened to me today. I'm working on an older version of Ruby on Rails (3.1.3) and hit a bug that the documentation said should have worked. Turns out that a bug had been introduced into the codebase and wasn't caught by any tests. It was fixed in a later version of Rails (3.2) but I was only able to ascertain the above because Rails is open source and I could work my way through the source code to trace the bug.

The scenario you describe likely happens more often than you think. Sometimes (often) documentation gets out of sync with code.