I have seen the other questions but I am still not satisfied with the way this subject is covered.
I would like to extract a distiled list of things
Documentation is like sex; when it's good, it's very, very good, and when it's bad, it's better than nothing