Write for the reader, not the auditor
Technical writing drifts into a defensive voice: passive, long, careful, addressed to nobody. I rewrote my 80,000-word book against nine rules and measured the result. Sentences got shorter, boxes got smaller, and the reader finally got addressed.
Engineers who write for regulated industries learn a particular voice. Every sentence is written as if an assessor will read it later and look for a weakness. Passive constructions hide who did what. Qualifiers pile up. Paragraphs grow until nothing in them can be quoted out of context.
That voice is right for a safety case. It is wrong for a book. My first draft of Sylang: MBSE for AI was full of it. The book is about audits, and I had written it for the auditor instead of for the person trying to learn.
So I wrote down the rules I wanted the book to follow, applied them to every chapter, and measured before and after with the same script.
Figure 1. Six measures over the whole manuscript. Grey is the original draft, orange is the edited book. Each row has its own scale.
The nine rules
1. Talk to one reader. Write you, not the engineer or one. A reader who is addressed keeps reading. You went from 1.7 to 9.9 uses per thousand words.
2. Say who did it. My draft referred to me as the author thirty times. That is how you write when you want distance from a claim. Now it says I where I mean me, and the author appears zero times.
3. One idea per sentence. Average sentence length fell from 16.7 to 13.6 words. The share of sentences over thirty words fell from 11.8% to 1.5%. Long sentences are where readers get lost and where weak claims hide.
4. Prefer the active voice. The validator is run before each commit becomes run the validator before each commit. Passive constructions roughly halved, from 7.3 to 3.8 per thousand words.
5. A box holds one point. The draft had 73 callout boxes over sixty words. A box that long is a section wearing a costume. Now none are over sixty words, every box has a title you can skim, and there are more of them: 359 became 400, because long boxes were split into two clear ones.
6. Break up the wall. Paragraphs over four sentences fell from 32 to 14. Lists nearly doubled, from 74 to 140, wherever the content really was a sequence or a set.
7. End each section with what to keep. Every chapter now has Key takeaways and Check yourself questions: 83 takeaways and 68 questions across 17 chapters. The questions reveal their answers on click, so they work as practice, not decoration.
8. Only claim what you can defend. Superlatives and round numbers I could not source were cut or softened. This is the one place where writing for the auditor is right: a book about evidence should hold up to its own standard.
9. No dashes. This one is personal taste. A dash usually hides a second sentence that should stand on its own. The draft had 881. The book has none outside code samples.
What did not change
The edit did not shorten the book. Prose grew about 6%, from 68,859 to 73,167 words, because takeaways, questions and clearer explanations take space. Code samples, diagrams and charts were frozen and came through byte for byte. The arguments are the same. They are just easier to follow.
| Measure | Before | After |
|---|---|---|
| Average words per sentence | 16.7 | 13.6 |
| Sentences over 30 words | 11.8% | 1.5% |
| Paragraphs over 4 sentences | 32 | 14 |
| Passive per 1,000 words | 7.3 | 3.8 |
| You per 1,000 words | 1.7 | 9.9 |
| Callouts over 60 words | 73 | 0 |
| Lists | 74 | 140 |
Why measure at all?
Style rules are easy to agree with and hard to apply evenly over 78 files. Measuring turned taste into something I could check. It also caught my own habits: I would not have guessed I wrote the author thirty times.
None of these numbers make a book good. They make it harder for a book to be bad in the usual ways. The rest is the reader’s call, and the book is free to read.