The voice, and the loop that improves it

In this chapter, we will learn the rules of voice that every book on this shelf follows, and the loop we use to improve a book after the first draft. The rules are short. The loop is what makes the difference.

Ten rules of voice

1. Plain words, short sentences. One idea in each paragraph.
2. Explain every term the first time. "A token is a small piece of text, roughly three quarters of a word."
3. Begin with the promise. "In this chapter, we will learn ..."
4. Definition first. One bold sentence, then the explanation.
5. One analogy for the whole book. The memory book has a card box, a secretary and a librarian. A chapter may add one small picture of its own.
6. One recurring character. The reader meets Maya in chapter 1 and still knows her in chapter 25.
7. Derive every number. Step by step, in a calculation block.
8. Say "we". The writer and the reader work it out together.
9. No hype. If something is good, the number will say so.
10. Tell the failures. What did not work is as useful as what did.

The skeleton of a chapter

the promise              "In this chapter, we will learn ..."
the analogy              one picture from everyday life
the sections             definition, picture, numbers, interactive
try it yourself          an experiment with real output
common questions         what a reader still asks
carry this               three to five lines
check yourself           questions with folded answers

The improvement loop

A review round is one pass in which a fresh reader checks the facts, reads as a beginner, and fixes what they find. We count what each round finds. When the count stops falling, the book is ready.

draft  -->  review round  -->  count: factual errors, unanswered questions, style  -->  fix
              ^                                                                         |
              +------------------  a NEW reviewer, who has not seen the book  ----------+

The reviewer makes three passes over each chapter.

Why a new reviewer each round?

A reviewer who has read the book once already knows what the writer meant. They can no longer see the gap. The same is true of the writer. A person who reads the chapter for the first time is the only honest test.

Who can review?

A friend outside your field is best. An AI assistant works well too, with clear instructions. The file tools/REVIEW.md holds the instructions we use. Give the reviewer your sources, so that they can check facts and not only style.

Try it yourself

Take one chapter you wrote. Give it to someone who does not know the subject. Ask for only one thing: "Underline every place where you had to read a sentence twice." Count the underlines. Fix them. Give the chapter to a different person.

Common questions

How many rounds are enough?

Stop when a round finds no factual errors and fewer than one open question per chapter. For the memory book we log every round in review-log.tsv.

Will plain language not bore an expert?

Experts skim, and plain text is the easiest to skim. What bores an expert is a claim without a number. Give them the measurements and the failures.

What if my subject has no numbers?

Then the interactive is a sorting task, a step-through or a small simulation. The memory book has all three: sorting sentences into kinds of memory, stepping through one request, and a simulator where you play a part.

Carry this

• Promise, analogy, definition first, numbers derived, failures told.
• A review round counts three things: factual errors, unanswered questions, style.
• Each round needs a reviewer who has not seen the book.

Check yourself

1. Round one found 40 problems and round two found 38. What does that tell you?

Answer

Either the fixes were not applied, or each fix introduced a new problem, or the chapters are too dense for the reader they are written for. Look at what kind of problem repeats before you start round three.