Status — Prototype reviewed
Tutorial code sample position
Question
Do readers prefer a complete code sample up front with explanation after, or code introduced incrementally?
Hypothesis
Experienced readers want the whole shape first; newer readers want it built up. A single article cannot serve both without an explicit switch.
Who it concerns
Developers implementing a described workflow.
Intervention
Annotated pseudocode blocks with inline comments as the primary form, kept short enough to read whole.
What would be observed
- Whether readers scroll back to the code after reading prose
- Whether annotations reduce follow-up questions
What would count as a useful signal
Readers can describe what each step does without re-reading the surrounding prose.
Notes
Next step: try a toggle between 'whole sample' and 'step by step' on one guide.
code samplesdeveloper education
This entry records a design intention. It does not report measured results, traffic, rankings, or customer outcomes.