One mode per document

Claim: each document serves one mode of reading (learning by doing, doing a task, looking something up, or understanding why) and says which.

What it asks

  • Four forms, from two axes (study against work, action against cognition) (Procida 2020):
    • a tutorial (learning by doing)
    • a how-to (one task, for someone who knows the basics)
    • a reference (facts to look up)
    • an explanation (why things are as they are)
  • One form per page; a page that needs two forms becomes two pages that link to each other.
  • A repository's front page answers what the project is, why it exists, how to install and use it, and its status. Why and status are the two most often missing (Prana 2019).

Why

Each form is read differently: a tutorial front to back, a reference by search, an explanation at leisure. Mixing them makes every reader skip what is not for them. The journal criteria for research software ask for the same parts: statement of need, installation, a real example, API, tests, community guidelines (JOSS; Lee 2018).

Limits

No controlled study compares readers on separated and mixed pages; the split is a framework, not a result. A small repository may be better served by one README holding several forms, signposted.

Practice agrees for a README. Three README guides, practice examples below the quality bar, put what it is, how to install it and how to use it in one file (Guo 2026; GitHub 2026a; Litt 2026, read from its example). This repository reads a README as an index of modes, not a breach; that reading is untested. On strict separation, a Hacker News discussion warns that a complete set can harm an early project (Hacker News 2024), and a Python discussion found mixing worked in one case (Viktorin 2022).

The README guides and the critics are both practice: convention, about what is done, not what it does to readers.