How to write this

This is the system. The chapters are what it produced. Use this file when you write the next one, with or without an agent.

The voice is not the point. The constraints are the point. If you keep the constraints, the voice shows up.

0. The test

Before you write a chapter, you must be able to say the whole thing in one sentence, out loud, without looking at notes.

Good: "A model is not a program. It is a pile of numbers that guesses the next token."

Bad: "This chapter covers architecture, training, and inference considerations for modern foundation models."

If you cannot pass the test, you do not understand it yet. Do not write. Read the primary source again until the sentence appears.

1. Who you are talking to

A programmer. About fifteen, if fifteen already ships code.

They know arrays, functions, APIs, what a process is. They do not know your field's words. They will smell condescension in one line and leave.

Do:

• Use if, map, "heap allocator," "S3" when those are the true picture.
• Define a field word the first time, in a clause, then use it.
• Stay concrete. A loop. A file. A number that changes a decision.

Do not:

• Explain what a function is.
• Write "simply" or "just" as a pat on the head.
• Write "as we shall see," "it is important to note," "in order to," "leverage."
• Open with a history lesson.

Graham's rule: write like you talk, then cut the parts you would not say to a smart friend at a table.

2. The unit is a chapter, not a book

A chapter is one idea. Not a topic. An idea.

Topic: "attention." Idea: "each token looks at the others and pulls a mix of what they are carrying."

If two ideas both feel load-bearing, that is two chapters. "MoE" and "all-to-all" look like one subject. They are not. One is the cheat. One is the tax.

Target length: 600–1200 words. Under 500, you probably skipped the consequence. Over 1500, you probably smuggled in a second idea.

Title the chapter with the idea, not the topic. "It's not a program." "The only trick." "All-to-all." "RL is a factory." A title you could put on a sticky note.

3. The spine of a chapter

Almost every chapter in this book is the same shape.

1. Unlearn. One sentence that names the wrong picture the reader already has.
2. The thing. The mechanism, in English, before any jargon.
3. The nickname. Now you may say weights, router, all-to-all.
4. One picture. A tiny loop, a table, or one mermaid. Not two.
5. Consequence. What this explains that was mysterious. What breaks. What people mix up.
6. Stop. Do not preview the next three chapters. One forward pointer is enough.

Chapter 3 is the cleanest copy of this shape. Steal from that, not from chapter 11.

4. Research before prose

You cannot write this book about something you half know. Plainness is a compression of a picture you already hold.

Order:

1. Collect primary sources only. Official cards, config.json, papers, lab blogs. Recap blogs are not sources.
2. Make a two-column sheet: confirmed (quote + URL) vs inferred.
3. Find the loop. Every system in this book is a loop. If you cannot draw the loop, you are still collecting vocabulary.
4. Write the one-sentence test for each planned chapter.
5. Then write. Do not outline twenty chapters before you have written three. The later names appear after the early ones exist.

When a number is a vendor claim, say so in the sentence that contains the number. Do not save the caveat for the end.

5. Words

Prefer short words. Prefer verbs. Prefer "you."

Kill on sight:

• utilize, leverage, robust, holistic, nuanced, landscape, space (as in "the serving space")
• "in order to" → "to"
• "the reason is because"
• "note that"
• "it should be noted"
• empty intensifiers: very, extremely, incredibly
• "simply," "just," "obviously," "clearly"

One analogy per idea. If you need a second, the first failed. Do not mix "notebook" and "food court" in the same paragraph.

Jargon arrives as a nickname after the picture. Bold it once. Then use it cold.

Numbers: only if they change what the reader believes. 512 experts. 16 bytes per parameter. A failure every 2.78 hours. A number that does not change the picture is a flex. Cut it.

6. What you are not writing

You are not writing a paper. A paper hides the simple thing under the new thing.

You are not writing a tutorial. A tutorial wants the reader to finish a lab.

You are not writing a tweet thread. Threads punch. This book sits.

You are writing the thing you wish someone had handed you on day two, after day one confused you on purpose.

A useful private test: would this paragraph still work if the reader cannot look anything up? If it depends on a word you have not earned, it fails.

7. How to start a new book

Pick a system you can hold as a loop. Not a field. A system.

Bad: "databases." Good: "what Postgres does when you type SELECT."

Then:

1. Write chapter 1 as unlearning. The wrong picture. The real object. Stop.
2. Write chapter 2 as the alphabet of the system (tokens, pages, packets).
3. Write chapter 3 as the only trick — the one loop everything else is a side effect of.
4. Read those three out loud. Cut 30%.
5. Only then list the rest. Each name must pass the one-sentence test.
6. Near the end, write the "what this is not" chapter, then the "what is still hidden" chapter if you went deep. Those two are how the reader learns to trust you.

Canon for the voice, in this repo:

• Shape: 03-the-only-trick.md
• Unlearning: 01-its-not-a-program.md
• Hard part, still plain: 19-all-to-all.md

If a draft does not sound like one of those three, it is not done.

8. Editing pass

After a draft exists, do these in order. Do not skip.

1. Read out loud. Anything you stumble on, cut or split.
2. One idea. Highlight the sentence that is the chapter. Everything that does not serve it goes to another file or the trash.
3. 30% cut. Not 10%. You will not cut enough the first time.
4. Jargon audit. Every bold word: does the previous paragraph already contain the picture?
5. Claim audit. Every number and every "they": is there a primary source? If not, soften or delete.
6. Consequence. Does the reader leave knowing why this matters, not only what it is?

Do not edit for "flow." Flow is what is left after you cut.

9. Running this with an agent

If an agent is drafting, the agent is a stenographer for a picture you already approved. It does not get to invent chapters.

Give it:

• the one-sentence test for the chapter
• the confirmed/inferred sheet
• "write like 03-the-only-trick.md"
• "no second analogy, no recap blogs, vendor claims labeled"

Then you do pass 8 yourself. The system fails if you accept the first draft.

There is a skill that encodes the same rules: plain-book (in your personal skills). Invoke it when you start a book, not after the draft is already a paper.