I agree with most of the points made here, though I think some of the bias toward up-front exhaustive documentation is probably not a good fit for most of the p

I agree with most of the points made here, though I think some of the bias toward up-front exhaustive documentation is probably not a good fit for most of the projects I've been a part of. Prototyping often reveals necessary changes due to resources constraints, or to unconsidered corner cases. Documentation needs to be a living thing as much as the code, and I think that pushes you toward documenting within the code more than externally. One of the more important points the author brings up is that authorial intent and the 'why's of comments are the most important. A corollary I'll bring up to that is that the 'what's should be encoded in tests. Tests can be great documentation, and they have the added benefit of informing developers when the goals of the software is being voided (when they fail). What has worked for me is conceiving of documentation this way: - Design Documents: Historical use only, not to be updated. - Readme: intro to project; why it exists, overview of how it's meant to function, how to edit, etc. Tends to be updated when big things change. - Code comments: why something exists, what considerations were made in that code's creation - Test descriptions and comments: binding goals of previous development to future development This approach has done a pretty good job of keeping documentation from getting too out-of-sync with code while enforcing basic business objectives, still tilting the balance toward development rather than documentation.