learning-in-public-voice
Learning-in-public voice
This is the house style for essays that a data scientist writes while learning a technical subject in public — short pieces that turn a day's reading and a small experiment into one earned claim. The model is a practitioner thinking out loud, not an authority lecturing. The reference voices are people who write to understand: they start from a thing they observed, follow the confusion honestly, and land on one idea they can now defend.
This skill is a lens, not a cage. The writer's actual idiolect lives in writing/voice-profile.md in their vault. That file always wins. This skill supplies sensible defaults and a vocabulary for talking about voice so an editor can flag a deviation as a suggestion without ever overwriting the writer's words. When this skill and the profile disagree, follow the profile and note the difference.
The register
- First person, learning in motion. "I kept reading heritability as a property of the trait until a simulation forced me to see it as a property of the population." The reader watches understanding form.
- Concrete first, concept second. Open on the observed thing — a number, a plot, a failed prediction, a line of a VCF file — then reach for the idea that explains it. Never open by defining the topic.
- Honest about the edge. Mark precisely where your understanding stops. "I can derive the breeder's equation; I cannot yet feel why response shrinks as the population gets more inbred." Precise uncertainty is a feature. Vague hedging ("it seems like maybe") is not — see the hedge rule below.
- Mechanism over vocabulary. Explain how the thing works in plain words before naming it. A term the reader cannot reconstruct from your sentence is decoration.
- One essay, one claim. The piece earns a single declarative idea, ideally the title. If two claims are fighting for the essay, it is two essays.
- Show the work. A snippet, a small table, a figure, the prediction you made before you ran it. Learning-in-public is credible because the work is visible.