No Words, No Excuses: Your README Could Learn Something From a Billy Bookcase
Photo: IKEA style wordless furniture assembly instruction manual diagram, via www.daily.uk.com
Last weekend I assembled a dresser while a nine-year-old supervised. The manual was eight pages, contained zero words, and communicated flawlessly across the entire spectrum of human confusion. Meanwhile, I spent thirty minutes that same week trying to install a popular open-source library whose README begins with the sentence 'It is assumed the user has a properly configured build environment.'
Assumed by whom? Defined how? The dresser never assumes. The dresser knows.
We worship at the altar of 'comprehensive documentation' and then produce 4,000-word READMEs that bury the actual install command under three paragraphs of project philosophy. A furniture manual has no philosophy. It has a picture of a dowel and an arrow. Consider what the flat pack knows that we don't.
Principle 1: One Step, One Outcome
IKEA instructions never say 'prepare the panels.' They say: here is panel A, here is panel B, here is the cam lock, insert A into B, twist. Done. Next picture.
Compare that to documentation that instructs you to 'set up your development environment' as a single step. That's not a step. That's a vibe. A step has an observable finish line — a command that returns something, a light that turns on, a drawer that slides. If your reader can't tell whether they've completed the step, you haven't written a step. You've written a wish.
Principle 2: The Diagram Before the Paragraph
The manual shows the finished dresser on page one. Not a mission statement. Not a changelog. The thing you're building, in full, so every subsequent dowel makes sense.
Good docs do this with an architecture diagram on the first screen. Bad docs do this with a 900-word 'Introduction' that restates the project name six times. When was the last time you read a README's introduction? Exactly. The picture of the dresser is doing all the work the introduction wishes it could.
Principle 3: Wordless Is a Feature, Not a Laziness
The genius of the wordless manual is accountability. When you remove language, you can't hide behind it. There's no 'simply' or 'just' or 'obviously' to lean on — if the picture is unclear, the picture is wrong.
Technical writing uses prose as camouflage. 'Leverage' hides that nothing is being explained. 'Note that' apologizes for the sentence you're about to read. Strip the words out and ask: does a diagram, a command, or a numbered sequence carry this? If yes, the paragraph was decoration.
Principle 4: The Spare Screw Is an Error Message
Flat-pack logic plans for failure. There's a spare dowel in the bag, an extra wall anchor, a phone number for the one part that always cracks. The manual even includes a section that is literally just pictures of things going wrong and how to notice them.
Your docs need a 'things going wrong' section drawn from reality, not imagination. Not 'Troubleshooting: contact support.' Actual failure modes: the exact error text, why it happens, what to type. The spare screw is the difference between a frustrated user and a user who fixes it in thirty seconds and moves on with their life.
Principle 5: The Hex Key Ships in the Box
Every IKEA kit includes the one tool you need. Not a link to a tool. Not a suggestion that a tool may be required. The tool, in the box, taped to the instructions.
Your documentation's equivalent is a copy-paste-able install block that actually works. Not 'install the dependencies' — the literal pip install or npm ci line, tested, in a code fence, on page one. If your reader has to figure out which tool to use, you've shipped furniture without the hex key, and they're assembling your project with a butter knife and resentment.
The Challenge
Here's the assignment, and yes, I did it to my own docs and yes, it was humiliating: take one README or API page you maintain and rewrite it using only diagrams, numbered steps, and commands. Zero hedging. Zero 'it should be noted.' Zero paragraphs where a picture would do.
If a step can't survive the translation to a picture or a command, that's not the reader's failure. That's a design problem in your software, and the manual just exposed it.
The Swedes figured out that clarity is kindness. Your users, standing in a half-built project at 11 p.m. with a mysterious error on screen, deserve the same courtesy the nine-year-old got. Eight pages. No words. Dresser stands.
Now go look at your README. Does it stand?