"its better to look at code" might be valid for tiny projects, but good luck making sense of million lines of code in thousands of files.... i'd rather have a d

"its better to look at code" might be valid for tiny projects, but good luck making sense of million lines of code in thousands of files.... i'd rather have a document with proper chapters / sections. it will always be easier to read. The problem is not with documentation ,but with the fact people are too lazy / distracted to update it along side their code. (i.e for every code you write, have the documentation open and verify it's still matching... / alter it where needed) documentation can also highlight easier program flow and other things which might not be clear from 1 code file or module. You could add such information in comments, but then you would need to be find that certain file with specific comments instead of just looking and ctrl+Fing in a document... i feel many people are against documentation just because they don't like to write it for whatever reason (maybe they just don't know how to concisely describe their own code...) if you look at companies who manage and own large code bases like HP and IBM, they have BIG documentation, and it's there for a good reason.... it's crucial to have. not having documentation is like programming something without any technical / functional design. it will become a mess sooner or later.