This month I wrote two documents with zero technical content. The first is a guide for my family. It explains each automatic thing our house does, and why. The second is a guide for my parents — the kids call them Oma and Opa. It covers the Muskoka house, so they can operate the house when I am not next to them.
Neither document explains how a system works. Each document tells what the house does, when it does it, and what to say if you do not like it.
The family guide opens with one sentence. I now think it is the most important sentence in the whole system: if something annoys you, that is useful information. Tell me the room and the approximate time. Then I can find the exact routine that caused the problem, and I can change it.
The nice-hotel test
That sentence exists because I failed a simple test. A smart home must feel like a good hotel. The room has the correct temperature when you enter. The path has light before you ask. You never think about the person who arranged it.
I built the opposite. I built a house that gave the family orders. I had installed middle management in the walls. Lights dimmed on people in the middle of a shower. A nightly cleanup routine started at the time people actually use the bathrooms. The bedtime routine shut down the kids’ TV room in the middle of a PS5 game. In this house, that is a war crime.
A complaint is a contribution
I could not find these problems myself. Each automation looked correct from the admin chair. The failures were visible only from inside another person’s evening. So the guide tells the family that a complaint is a contribution. The guide also keeps a public record to show that the complaint box works: what a person said, and what changed.
“The lights dimmed on me mid-shower” became a standing rule. The house does not dim a light on a person in the shower. Ever. The kids did not want the routines in their bedrooms at all. Their rooms are now out of every automatic routine. Only functions they request by name touch their space.
The PS5 problem became a check. The bedtime routine looks first. If a game runs in a room, the routine skips that room. Every fix shipped within 48 hours of the complaint. The speed matters more than the fixes. Speed is the reason people continue to tell you things.
One rule came out of all this. Automatic routines touch only shared spaces. Your bedroom, your speakers, and a room you use at that moment are off limits. If the house interrupts you anyway, that is a bug. I want to hear about the bug the same day.
The one-paragraph test
The guide for Oma and Opa taught me a different lesson. My parents set a constraint that no code review sets. Each behavior gets one paragraph of plain language. If I cannot explain a behavior in one paragraph, the behavior is wrong.
A shade that closes itself on hot afternoons passes the test. One sentence, one obvious reason. The guide adds one note: open the shade by hand, and it stays open for the day. A house that closes a shade you just opened is rude.
Some automations failed the paragraph test. They were not broken. They were unexplainable. That is the same thing. I deleted them. I did not document them.
The rest of that guide is hospitality in table form. The exact phrases to say. The three rules that correct almost every problem. A section named “when something misbehaves” ends every row the same way: call me, because I can see the whole house from my phone. The guide also has an honest note about the one fragile part of the setup. The instruction is: telephone me before you reboot anything. To admit a weak part is friendlier than to hide it and let them find it alone.
The audience shaped the system
I used to think documentation was the chore after the real work. These two guides reversed that idea. The audience shaped the system. I explained the house to the people who live in it, in their language, at their level of interest. That explanation was the design review that found the real problems, because the reviewer is the person the design is for.
The wall switches still work. The complaints stay welcome. Everything is a setting, not a law of physics. That last sentence is in the family guide too. It could be the second most important sentence.