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.
Sometimes, all it takes to teach something is to find the perfect example
— Matt Pocock
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, MIT; source file: skills/.
Retrieval
Close the explanation and answer unaided.
Spacing
Return later and record what you forgot.
Interleaving
Mix related problems that require different choices.
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.
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.
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 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
- skills, MIT source for the teaching structure; file identified above.
skills MIT notice
The structure adapted here comes from mattpocock/skills, MIT licence, Copyright (c) 2026 Matt Pocock. The complete licence follows, identical to the repository LICENSE.
Full licence: mattpocock/skills
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.