Every project here writes documents that people read: READMEs, tutorials, status pages and forum posts. This guide says how to write them so that a newcomer can follow. It serves the first of the four virtues that every project here follows, set out in OCX, the workbench these projects share: each part must be clearly stated.
Write for a novice: someone who can read code, but who doesn't know this project, its tools or its history.
1. Know which kind of document you're writing
Most hard-to-read documents mix several jobs. Keep each one to a single job. These four kinds come from Diátaxis, a widely used way of organizing documentation, described by Daniele Procida:
- Tutorial: teaches by doing. The reader follows steps and ends with something working. It explains only what the next step needs.
- How-to guide: gets a task done for someone who already knows the basics. It gives steps, not lessons.
- Reference: describes exactly what something is or does, such as a command, a format or an interface. It is complete and dry, and it is not read from start to finish.
- Explanation: says why. It gives the background, the choices made and the alternatives. It has no steps.
When a tutorial starts explaining the history of a design, move that part into an explanation and link to it.
2. Define each word where it first appears
Explain an unfamiliar word in the sentence that uses it, in a few words: "handling interrupts (signals from a device that make the processor stop and respond)". Don't send the reader to a glossary. Looking away to another place and back costs more effort than reading a short definition in line. Learning researchers Paul Chandler and John Sweller call this the split-attention effect.
Define a word once, at its first use. After that, use the same word every time; a new word makes the reader wonder whether it's a new thing.
3. Show a whole step, then hand the reader more
In a tutorial, show the first example completely: the code, the command and what happens. Then let each later step leave a little more to the reader. Researchers (John Sweller, Alexander Renkl) call these faded worked examples: complete examples at first, with parts gradually left out. They work better for beginners than either all-explanation or all-exercise.
Every step ends with something the reader can see working, such as a test passing, a message on the screen or a page loading. That is the virtue of being demonstrably verified (shown working, not just claimed), applied to teaching.
4. Let the reader act early, and cut the rest
John Carroll, who studied how people learn from manuals, found that readers learn best when they start doing real work right away. He called this minimalism. So get the reader doing something real in the first few lines. For each paragraph, ask: would the reader miss it if it were gone? If not, cut it. Background can come later, or go in an explanation.
5. Write plain sentences
- One idea per sentence, and one topic per paragraph.
- Use short, common words, and active voice: "Glint loads the guest", not "the guest is loaded".
- Put the main point first: what happened, what it means, what to do.
- Name things the same way every time.
- BeagleBoard.org's boards have names that work like a friend's name, so write "BeagleConnect Zepto runs…", never "the Zepto". Writing "the board" is fine.
- Speak of the reader generically, as "a novice" or "a new user". Don't name a particular person unless the fact is about them.
6. Test it with a cold reader
Before a document lands, give it to a cold reader: someone with no context. A new AI agent session that has read nothing else works well. Ask it to:
- explain back, in two sentences, what the document is about and why it matters;
- answer two or three questions that the document should answer;
- list every word it had to guess at;
- name the hardest sentence.
If its answers are wrong, fix the document, not the reader. Define each guessed word in place. Rewrite the hardest sentence. Then repeat the test until the answers match what you meant. A real novice, when one is willing, is the final test.