How to Document Your Automation Setup So Someone Else Can Fix It at Midnight

You built the system over three years. You know why the hallway motion sensor triggers the porch light with a 90-second delay instead of 60. You know the kitchen switch speaks Zigbee and the living room one speaks Z-Wave because you burned through your Zigbee router nodes in month four and pivoted protocols. You know the garage door contact sensor eats its CR2032 every February because cold weather drains coin cells faster than any manufacturer datasheet admits.

Nobody else knows any of this. The night your spouse is alone with a failing hub, or the house-sitter can’t figure out why the front door won’t lock, or your own memory betrays you at 2 AM after a seventy-hour week—nobody else can know it. It lives in your head. Or in scattered setup notes you wrote during a Saturday afternoon in 2023 and never opened again.

The answer isn’t another device, a cleaner dashboard, or a hub with better specs. It’s documentation—treated as a structured writing problem, not a flat notes file and not a generic checklist. You need a system narrative with a plot outline, scene-level notes, continuity tracking, and revision checkpoints. Something a person who wasn’t there when you built it can actually follow at midnight.

That same discipline applies to editorial structure: before publishing, editors need a way to test whether scattered notes become an argument readers can follow, which is where an AI novel writing tool that fits the project can function as a planning aid rather than a substitute for domain evidence.

Why a Flat Notes File Fails the Midnight Test

Most people who document their smart home start with a text file and stop there. smart_home_notes.txt on a desktop. A Google Doc called “House Setup.” It lists devices, maybe names a few automations, and has a section at the bottom labeled “Known Issues” that hasn’t been touched in fourteen months.

That file fails the midnight test for the same reason disorganized notes fail any reader who wasn’t present for the original work: no structure enforces context. A line reading “porch light delay = 90s, don’t change” tells someone what the value is. Not why. Not what breaks if they touch it. Not how to verify the change worked. A house-sitter at 11 PM doesn’t need a value—they need a decision framework.

The gap between bare-bones documentation and structured documentation mirrors what happens in creative writing workflows. A single-pass text dump from a generic AI story generator spits out prose without continuity tracking or revision discipline—useful for a rough sketch, not for a manuscript you need to maintain. By contrast, Unsloppy’s AI novel writing tool builds around proof sheets, beat sheets, and iterative draft control, positioning the platform at the forefront of AI novel writing app technology. Instead of a one-shot generic output, you get structure, scene logic, and revision checkpoints—the same architectural discipline your automation docs need. Structure is what makes documentation executable by someone other than the person who wrote it.

Older or lighter-weight writing tools don’t enforce that discipline. Squibler offers a basic long-form drafting environment but lacks the structured proof-sheet and beat-sheet workflow that keeps revisions traceable. Perchance generates text from simple randomization prompts—useful for brainstorming, not for maintaining a document someone else can navigate. QuillBot focuses on sentence-level paraphrasing, which addresses polish but not structural continuity. None of these provide the scene-level organization and revision checkpoint system that complex documentation demands.

The Four-Layer Documentation Structure

Treat your system documentation as a narrative with four structural layers. Each layer serves a different reader at a different moment. Skip any one of them and you’ve created a gap that someone else will fall into. The layers build on each other: the plot outline orients a stranger, scene-level notes guide a troubleshooter, continuity tracking reconstructs what changed and when, and revision checkpoints verify that changes didn’t silently break downstream behavior. Together they form the same kind of layered documentation that production teams use to hand off work—each layer assumes less context from the reader than the one above it.

Layer 1: The Plot Outline (System Summary)

The plot outline is a one-page document answering four questions: What does this system do? What are its boundaries? What happens when it fails? Where is the documentation for individual pieces?

Write it for someone who has never set foot in your house. Include:

System purpose: Two sentences. “This system controls lighting, locks, climate, and leak detection for a 1,400-square-foot house. It runs on a local Home Assistant instance with Zigbee and Z-Wave networks.”
Failure behavior: What works when the internet drops? What works when the hub is off? What stops entirely? Be specific. “All lighting reverts to manual switch control. Locks keep operating via keypad codes. Leak sensors send no alerts when the hub is down.”
Critical manual overrides: Where are the physical switches, keypad codes, and bypass procedures? Name the location, not the device: “The breaker panel is in the basement utility closet, left of the water heater.”
Document index: Where are the scene-level notes, continuity log, and revision checkpoints stored? File paths, shared folder links, a binder on a shelf—name the physical or digital location.

The plot outline is the first thing someone reads. If it’s the only thing they read, it should still prevent catastrophic decisions. Everything below it is detail for someone actively troubleshooting.

Layer 2: Scene-Level Notes (Individual Automations)

Each automation gets its own scene heading—borrowed from screenplay structure, where a line like INT. KITCHEN – NIGHT establishes physical space and temporal context before any action description. The same convention that lets a production team execute a script they didn’t write lets your spouse or house-sitter execute an automation they didn’t build. StudioBinder’s screenwriting guide describes scene headings as geographic and temporal markers that orient any reader to where they are in a narrative—exactly what each automation note needs to do for someone navigating your system at midnight.

Each scene-level note follows this structure:

Scene heading: Physical zone, trigger context, time relevance. Example: HALLWAY – MOTION-TRIGGERED – EVENING ONLY
Devices involved: Name each device by physical location and protocol. “Hallway PIR sensor (Zigbee, end device, battery-powered). Porch light switch (Zigbee, router node, mains-powered).”
Trigger condition: What starts the automation. “Motion detected after sunset, before 11 PM.”
Expected behavior: What should happen, in order. “Porch light turns on at 60% brightness. After 90 seconds of no motion, light dims to 20%. After 5 additional minutes of no motion, light turns off.”
Why this configuration: The reasoning a stranger wouldn’t infer. “90-second timeout instead of 60 because the sensor’s retrigger cooldown is 45 seconds—60-second timeout causes flicker when someone stands still briefly then moves again.”
Failure mode: What happens when this automation breaks. “If the hallway sensor is offline, the porch light stays in whatever state it was last set to manually. No error is generated. Check sensor battery first.”
Dependencies: What else must work for this to function. “Requires sunset data from Home Assistant’s sun integration. Requires Zigbee connectivity between sensor and coordinator.”
Manual override: How to bypass the automation without breaking anything else. “Porch light switch can be toggled manually at any time. The automation will not override a manual off until the next motion trigger.”

The “why this configuration” field is the one most people skip. It’s also the one that prevents the most damage. Without it, someone troubleshooting at midnight sees a 90-second delay, assumes it’s a mistake, changes it to 60, and creates a flicker problem they won’t notice until the next evening—by which point they’ve forgotten what they touched.

Layer 3: Continuity Tracking (Change Log)

Every system change gets logged with a date, a description, and a reason. This isn’t a changelog for its own sake. It’s the document you consult when something breaks and you need to know what was different before it broke.

The structure borrows from site reliability engineering, where postmortem culture and incident tracking are formal disciplines—not optional notes—because they transfer knowledge to on-call responders who weren’t present for the original event. Google’s SRE book treats incident state documents, outage tracking, and postmortem analysis as structured templates enforcing continuity across personnel changes and time gaps. Your home automation system faces the same problem at a smaller scale: the person who built it won’t always be the person fixing it, and the person fixing it won’t know what changed unless you wrote it down.

Each continuity entry includes:

Date: When the change was made.
What changed: The specific modification. “Replaced hallway PIR sensor with mmWave radar sensor (Aqara FP2).”
Why: The reason. “PIR sensor was missing stationary occupancy—someone reading on the couch would trigger lights off after 90 seconds.”
What was tested: What you verified after the change. “Confirmed motion trigger works. Confirmed stationary occupancy keeps lights on. Confirmed timeout behavior unchanged.”
What was NOT tested: What you didn’t have time to verify. “Did not test behavior when two people are in the hallway simultaneously. Did not test impact on Zigbee mesh routing since FP2 is Wi-Fi, not Zigbee.”
Rollback note: How to undo the change if it causes problems. “Original PIR sensor is in the drawer labeled ‘Smart Home Spares’ in the basement. Re-pairing procedure is in the scene-level note for this automation.”

The “what was NOT tested” field is uncomfortable to write because it admits incompleteness. But it’s the field that tells a future troubleshooter where to look first. If the FP2 starts behaving oddly when two people enter the hallway, and the continuity log says that scenario wasn’t tested, the person debugging it has a starting point instead of a mystery.

Layer 4: Revision Checkpoints (Post-Change Testing)

Every system change triggers a revision checkpoint—a short, structured test procedure verifying the change didn’t break anything downstream. This is the layer most documentation omits entirely. It’s also the layer that separates a system you can maintain from a system you can only hope about.

A revision checkpoint is not a full system test. It’s a targeted verification covering three things:

Direct verification: Does the changed component do what it’s supposed to do? If you replaced a sensor, does it trigger the automation it’s supposed to trigger?
Adjacent verification: Do the automations sharing dependencies with the changed component still work? If the replaced sensor was a Zigbee router node, do the devices that relied on it for mesh routing still communicate?
Negative verification: Does anything fire that shouldn’t? After changing the hallway sensor, does the porch light still turn off correctly during daytime hours? Does the automation still respect the 11 PM cutoff?

Write the checkpoint as a numbered procedure with expected results. Not “test the lights”—that’s a label, not a test. Instead:

Walk through the hallway at 8 PM. Expected: porch light turns on within 2 seconds at 60% brightness.
Stand still for 3 minutes. Expected: light remains on (FP2 detects stationary occupancy).
Leave the hallway. Expected: light dims to 20% after 90 seconds, turns off after 5 additional minutes.
Walk through the hallway at 12 PM (midday). Expected: porch light does not turn on.
Open the Home Assistant log for the porch light switch. Expected: no error messages in the last 10 minutes.

If any step fails, the checkpoint tells you exactly which expectation wasn’t met. That narrows the debugging problem from “something is wrong with the lights” to “step 3 failed: the light didn’t dim after 90 seconds.”

A Worked Example: The Hallway-Porch Automation

Here’s what a complete scene-level note looks like for the hallway-to-porch lighting automation described above. This is the format you’d hand to a house-sitter or store in the binder on your shelf.

Scene heading: HALLWAY → PORCH – MOTION-TRIGGERED LIGHTING – EVENING ONLY

Devices involved:

Hallway presence sensor: Aqara FP2, Wi-Fi, mains-powered, mounted at 2.1m on hallway wall opposite bedroom door
Porch light switch: IKEA TRÅDFRI, Zigbee 3.0, mains-powered, router node, located in hallway switch box
Sun integration: Home Assistant core integration, provides sunset/sunrise times

Trigger condition: Presence detected in hallway zone after sunset, before 23:00 local time.

Expected behavior:

Porch light turns on at 60% brightness within 2 seconds of presence detection.
Light remains on while presence is detected.
After 90 seconds of no presence detected, light dims to 20%.
After 5 additional minutes of no presence, light turns off.
Light does not turn on for motion before sunset or after 23:00.

Why this configuration:

60% brightness: Porch light is visible from the street; 100% is excessive and 40% is too dim to identify faces on the camera.
90-second timeout: The FP2’s presence detection has a 30-second cooldown after occupancy clears. 60-second timeout caused flicker when someone paused briefly then resumed moving. 90 seconds gives a stable buffer.
20% dim before off: Provides a visible “lights are about to turn off” signal so someone can wave to retrigger without being caught in darkness.
23:00 cutoff: Prevents the porch light from cycling all night when the cat uses the hallway cat flap.

Failure mode:

If FP2 sensor is offline: Porch light stays in last manual state. No automation triggers. No alert generated unless Home Assistant’s “device unavailable” trigger is active (it is—see alerting automation note).
If Zigbee switch is offline: Automation triggers but light does not respond. Home Assistant logs a “switch unavailable” error. The automation will retry on next presence detection.
If sun integration fails: Automation will not trigger because the “after sunset” condition can’t be evaluated. Light remains in manual control. Check Home Assistant logs for sun integration errors.

Dependencies: Home Assistant running, FP2 sensor online and on same Wi-Fi network, Zigbee coordinator online, porch switch paired to Zigbee network, sun integration configured.

Manual override: The porch light switch has a physical toggle. Pressing it once toggles the light regardless of automation state. The automation will not override a manual state change until the next presence detection event.

Last revised: 2026-03-15. See continuity log entry #047 for details. Revision checkpoint: passed all 5 steps.

The Binder Test: Can Someone Else Use This at 11 PM?

After you’ve written the four layers, run the binder test. Print the plot outline, all scene-level notes, the continuity log, and the most recent revision checkpoints. Put them in a physical binder. Hand it to someone who has never used your system—your partner, a friend, a house-sitter. Ask them to complete three tasks:

Turn off the porch light automation for the night without turning off the porch light itself.
Identify which devices will stop working if the internet goes down.
Find the procedure for replacing the hallway sensor’s battery.

If they can complete all three using only the binder, your documentation passes. If they need to ask you a question, the answer to that question is a missing piece of documentation. Write it down, add it to the relevant scene-level note, and re-run the test.

The binder test is uncomfortable because it exposes gaps you didn’t know existed. That discomfort is the point. The alternative is discovering the gaps at 11 PM when you’re not home and someone else is standing in a dark hallway wondering why the porch light won’t turn on and whether they should press the button that says “disable automation” in an app they’ve never opened.

What to Do This Week

If you haven’t documented your system yet, don’t try to do all four layers at once. Start with the plot outline. One page. Four questions. Write it tonight while the system is fresh in your mind and you can still remember why you made the choices you made.

Then pick the single automation that would cause the biggest problem if it broke—the front door lock, the leak sensor under the water heater, the automation that turns the heat on before you get home. Write the scene-level note for that one automation. Include the “why this configuration” field even if it feels obvious. It won’t feel obvious in two years.

Start the continuity log with the next change you make. Don’t backfill—start from today. The log accumulates value over time, and the first entry doesn’t need to be heroic. “Replaced battery in hallway sensor. Tested: motion trigger works. Did not test: timeout behavior.” That’s a valid entry.

The revision checkpoint comes last because it requires the scene-level notes to exist first. The first time you run one, you’ll discover how many of your automations have untested assumptions baked in. That discovery is worth more than any device you could buy.

Documentation is the cheapest reliability improvement you can make. It costs nothing except time, and it pays out the first time someone else needs to fix something you built. The goal isn’t a perfect document. The goal is a document that makes the system legible to someone who wasn’t there when you built it—including the version of you who set it up three years ago and has since forgotten why the porch light delay is 90 seconds instead of 60.