Documentation: how to structure a repository's pages and its code comments

Question: what must a repository's documentation contain, how should its pages be separated, and what should a code comment carry, so the reader finds and trusts it.

Steps: frame · review · state of the art · position · against · baseline · bibliography

Claims

Claim	Grade	Where
Comment quality clusters on consistency, completeness and usefulness	supported with caveat	review.md 1
Code and comments drift apart; inconsistency is the dominant decay mode	measured, on large corpora	review.md 1
READMEs commonly answer What and How; Why and project status are often missing	measured, descriptive	review.md 1
A page should keep one form: tutorial, how-to, reference or explanation	convention, untested	review.md 2
Research software needs need, install, example, API, tests, community guidelines	convention, adopted by a journal	review.md 2
A comment earns its place only by carrying what the code cannot	convention, untested	review.md 3
Declaration comments describe use; definition comments describe operation	convention, untested	review.md 3
Error messages should point at their fix	convention, untested	review.md 2
A README is an index of modes by convention, not a mixed page	convention, untested	position.md
Diataxis adoption is self-reported; critics name the cost of strict separation	convention, untested; adoption descriptive	review.md 4, against.md