From the excellent “Coders at Work” by @peterseibel – Ken Thompson answers a question on documentation:

Documenting is an art as fine as programming. It’s rare I find documentation at the level I like. Usually it’s much, much finer-grained than need be. It contains a bunch of irrelevancies and dangling references that assume knowledge not there. Documenting is very, very hard; it’s time consuming. To do it right, you’ve got to do it like programming. You’ve got to deconstruct it, put it together in nice ways, rewrite it when it’s wrong. People don’t do that.