[nsonha]

isn't the first problem of documentation is keeping it in sync with the source code? Time and time again people come up with "better ways of documentation" while neglecting this basic problem, what problem do they think they're solving?

[tyzoid]

Yes, but the closer the documentation is to the code, the easier it is to keep up-to-date. I've found anecdotally that other developers on my team readily update doc-comments when method signatures change, but update out-of-file documentation less readily (such as a markdown readme document).

Structuring the documentation as part-and-parcel of the code helps give the documentation a fighting chance of staying up-to-date over time given without requiring all developers on the team from being religious about updating docs (which I find I need to enforce at the PR stage for those repos with external readme files).