I started my new job. In those days I'm meeting a lot of people, and getting acquainted with a good amount of documentation. Sometimes it is clear, sometimes it is not.
Everybody knows how documentation is prone to be problematic. The task of documenting something is very difficult, because one has to drop the knowledge and describe things in a simple way. It is difficult to draw a line and separate the stuff you will document by the stuff you will give for granted.
The other problem is usually lag: documentation is bound to be lagging behind the code. Two factors are involved here:
The code is the thing you need done, much more than what documentation is (the software will run if not documented, but the documentation by itself will not make the software);
The code will describe in a precise way what the software does.
Thinking of these facts, I realized two important points of awareness:
High-level languages are important as a way to define logic in a more readable way. You don't realize it, but you do that because the code gets more and more similar to be documentation. And if you have to describe unrelated lower-level stuff, whoever reads the code will lose grasp on it)
Documentation is usually bad because it's a direct violation of the Single Point of Truth principle. That's why auto-documentation tools exist. Note that if you violate this rule within code you will have a difficult-to-maintain software, while if you violate the rule with documentation you get bad documentation.
Corollaries:
This always happens by definition, since the code is not the documentation;
Software goes rotten with independent patterns. You can have a really perfect software (never happens, though) with really poor documentation.