Thank you for saying that, I sometimes feel like I'm taking crazy pills when I hear some of the inane arguments against thorough documentation.
I was hoping this was going to be about the real "documentation fallacy:" 'Documentation tends to be of low quality, therefore it is best to avoid writing much documentation.' One common instantiation of this is "thorough documentation is bad because it will inevitably fall behind the code and be inaccurate."
People fall into the trap of assuming there is something inevitable about bad docs. Yet they never assume there is anything inevitable about bad code, even though most of the code in the world is, objectively, complete shit!
I think this whole thing sits in the same boat with error handling and unit tests. Many folks tend to see these as something separate from programming. Some kind of side effect that isn't a lot of fun and is therefore best ignored. "Hey, I can write me some code.. and oh yea.. there's also this bit of stuff I should do, but I'm busy writing the next big thing."
It helps to start thinking of all this as one and the same. No single part of it is more or less important. If you are writing code, you are writing documentation, you are doing correct and thorough error handling and you are producing consistent and relevant tests. There is no difference.
I was hoping this was going to be about the real "documentation fallacy:" 'Documentation tends to be of low quality, therefore it is best to avoid writing much documentation.' One common instantiation of this is "thorough documentation is bad because it will inevitably fall behind the code and be inaccurate."
People fall into the trap of assuming there is something inevitable about bad docs. Yet they never assume there is anything inevitable about bad code, even though most of the code in the world is, objectively, complete shit!