[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).