This is, of course, the toughest documentation problem. Nevertheless, it must be solved. One way to solve it is to hold any major release until the docs are satisfactory. I'm not talking revisions here, I'm talking releases. So we have yet to cross that bridge, but we're coming to it.
Another accuracy issue is the accuracy of the annotations of examples in component docs: it's perfectly possible to POE perversely without realizing it. So any examples that have misinterpretations in explanations of core features need revision.
This is not so tough to deal with, just strongly suggest that component implementors leave out any explanations of what the core is doing and point to the appropriate docs instead. This is a gram of prevention; currently it isn't much of a problem.