# Writing to Teach Begin with a reader’s concrete problem, then check learning with a new problem. ## Give readers a reason An explanation promises a powerful, flexible, efficient system. Readers still cannot decide what to do. Start with a specific puzzle instead: why does the interface claim success after saving fails? Use a real problem without inventing a personal story. ## Give the concept somewhere to land Describe the consequence, explain its cause, introduce a method and test it in one small situation. A before-and-after comparison makes the change visible. Introduce one example for each concept before adding variations. Figure: Teach through a concrete problem, its cause, a method and an example. ([s16-lesson-order](/art/s16-lesson-order.en.svg)) > Sometimes, all it takes to teach something is to find the perfect example > > — Matt Pocock, [source](https://x.com/mattpocockuk/status/1994475432763113845), 2025-11-28 ## Make sentences do work A concrete verb can point to behaviour. Preserve the input after validation fails gives readers something to implement and inspect. A claim about a transformed experience leaves the action unspecified. | Wording | What a reader can do | | --- | --- | | Use robust validation | Guess where to start | | Name the invalid field and preserve the input | Implement and inspect one behaviour | Short sentences, space and comparisons help readers follow the idea. British slang, profanity and particular punctuation choices are not requirements for good teaching. Remove sentences that change no action, then check that the necessary limits remain clear. Inspect the example’s input and expected outcome separately. Without an input, readers cannot identify the situation; without an expected outcome, they cannot check an answer. Preserve the information needed for the decision before removing decorative wording. ## Close the explanation Adapted from Matt Pocock's [skills repository](https://github.com/mattpocock/skills), MIT; source file: `skills/productivity/teach/SKILL.md`. - **Retrieval** Close the explanation and answer unaided. - **Spacing** Return later and record what you forgot. - **Interleaving** Mix related problems that require different choices. Figure: Retrieval and spaced practice test whether learning transfers to new problems. ([d16-practice-loop](/diagrams/d16-practice-loop.en.svg)) Teach one small concept, then ask for a decision. Define completion as handling an unfamiliar input. Reading smoothly is insufficient evidence. The complete licence follows at the end of this page; see also the [copyright page](/en/about-and-copyright). ## Check the teaching too AI explanations can contain factual errors. Keep reliable sources for key claims and have a person check examples and answers. Correlations involving likes or bookmarks in an archived sample do not establish that a writing technique causes learning. > **Our inference** > Our suggestion: separate checkable facts, example assumptions and application advice. Verify facts against sources, inspect example behaviour and state the conditions attached to advice. ## Exercise: replace the adjectives ### Turn a claim into a lesson - Draft: our import feature is powerful, intelligent and easy. - Task: provide a reader problem, one method and an observable result. - Variation: replace a missing name with a duplicate identifier. Suggested approach: One row lacks a name: return its row number and field, then allow a corrected import. Duplicate identifiers require identifying the conflicting rows; the missing-field answer is insufficient. Done means another reader can predict the feedback from your explanation and justify an answer to the variation. Continue with [feedback and attribution](/en/feedback-and-attribution) to improve the lesson. ## Quick reference - **Opening** Name a specific difficulty or goal. - **Development** Problem, cause, method, concrete example. - **Completion** Solve a fresh problem and check behaviour and sources. ## Sources - [Matt on teaching examples, 2025-11-28](https://x.com/mattpocockuk/status/1994475432763113845) - [skills, MIT source for the teaching structure](https://github.com/mattpocock/skills); file identified above. ## skills MIT notice The structure adapted here comes from [mattpocock/skills](https://github.com/mattpocock/skills), MIT licence, Copyright (c) 2026 Matt Pocock. The complete licence follows, identical to [the repository LICENSE](https://github.com/mattpocock/skills/blob/main/LICENSE). ### Full licence: mattpocock/skills ```text MIT License Copyright (c) 2026 Matt Pocock Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ``` Unofficial, non-commercial study notes. No affiliation with or endorsement by Matt Pocock. Quoted works remain their authors’ copyright; MIT reuse retains its copyright and licence notices. The diagram CSS on this page is adapted from Archify (https://github.com/tt-a1i/archify) under the MIT licence; the complete licence follows. ### Full licence: Archify (tt-a1i/archify) ```text MIT License Copyright (c) 2026 tt-a1i (Archify) Copyright (c) 2025 Cocoon AI Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ```