Reader style: a newcomer to the system
How the software design principles change when the reader is a developer new to the system, reading to start contributing. It has three parts: who the reader is, the overrides, and what is open.
Who
- Reader: a developer who has just joined a project and needs to see where a first task fits.
- Expertise: intermediate or expert in the language; a novice in this system, its parts and its reasons.
- Medium: a screen, beside the code.
- Reading mode: once from the start, for the whole; then by search, from a task to the part that holds it.
Overrides
| Principle | Change | Why |
|---|---|---|
| Order a description by the reader's questions | strengthen: the overview and the map of parts come first, so a newcomer sees where a task fits before any detail | newcomers sought the architecture mostly for a broad view and to place their task (Dagenais 2010, 18 newcomers in 18 projects, secondary) |
| Order a description by the reader's questions | add: name each part as the code names it, and point from each part to where it lives | prior familiarity with the code dominated newcomers' scores (Ernst 2023, 65 students); the codemap convention (matklad 2021) |
| Keep the options that lost | add: link the decision records from the description, so a newcomer finds why without asking | convention, untested |
| (task excerpts) | for a large description, offer a short excerpt per common task | proposed by Rost 2016, with a later thesis reporting better retrieval (secondary) |
Thresholds
None changed.
Open questions
- No study measures newcomers with and without decision records.
- Whether task excerpts help on their own, outside the thesis that proposed them, is not known.