Most smart-home and small-office setups run on one person’s memory. That works great—until it doesn’t. The right time to write down what you’ve built isn’t after a 2 a.m. failure. It’s on a boring Tuesday when everything still hums along. This guide lays out a plainspoken, systematic way to document your automation setup so another reasonable adult can read it, understand it, and fix it. Even at midnight. Even when you’re not answering your phone.

Why Most Automation Documentation Fails

Most people don’t document at all. The few who do often scribble notes only they can decode. A line like “Living room motion triggers off when mode=away” makes perfect sense to the builder. To someone else at midnight, it’s half a sentence. Good documentation assumes the reader is competent but knows nothing about your specific choices. It tells them where things live, what they’re called, how they connect, and what to do when a light refuses to turn off.

Documentation usually fails for three reasons: it’s scattered across apps and sticky notes, it’s written in shorthand that rots over time, and it skips the “why” behind a rule. A friend or family member troubleshooting in the dark doesn’t need your lighting philosophy. They need to know which breaker feeds the hub and which app to open first.

Start With the Physical Layer

Before you jot down a single rule, walk through your space and list every device that talks to another device. Hubs, bridges, smart plugs, sensors, wall switches, anything with a battery. Give each one a plain-language name and note its location, power source, and network connection.

Build a Simple Device Inventory

Use a spreadsheet or a shared note that lives both offline and online. For each device, record:

• What you call it (e.g., “Basement water sensor”)
• Where it sits physically
• How it gets power (outlet, battery type, hardwired)
• Which hub or app controls it
• Network type (Z-Wave, Zigbee, Wi-Fi, Thread, Bluetooth)
• Date installed or last battery change

This inventory is the foundation. If a motion sensor dies, the reader can cross-reference the name, find the physical device, and know it takes a CR2450 battery, not a AAA. That saves an hour of fumbling at midnight.

Label the Real World

Small adhesive labels on hubs, power adapters, even inside battery compartments make a real difference. Use a label maker or a permanent marker to write the device name that matches your inventory. “Smart Hub 1 – Living Room Shelf” beats a cryptic model number any day. If a device hides behind furniture, add a note in the inventory: “Behind TV stand, reach from left side.”

Label circuit breakers too, especially if you’ve added dedicated lines for a server closet or a PoE switch. A midnight reset often starts at the breaker panel.

Map the Logical Layer

Once the physical list exists, document the rules and routines that make the system behave. This is where most setups turn opaque. A rule like “Turn off all lights at 11 PM unless the TV is on” is simple to describe in plain language. Inside an app, it might be three separate automations spread across two platforms.

Write Automation Descriptions in Plain Sentences

For each routine, scene, or automation, write a single sentence that includes the trigger, the condition, and the action. For example:

“When the back door opens (trigger) and it’s after sunset (condition), turn on the mudroom light for five minutes (action).”

Group these sentences by room or function. Keep them in a document that can be printed or viewed on a phone. Avoid screenshots alone; screenshots go stale when an app updates its interface. Plain sentences outlast UI changes.

Document the Dependencies

Many automations lean on other automations or on a specific device state. If a morning routine won’t run unless the alarm is disarmed, write that down. If a water shutoff valve triggers only when the leak sensor and the away mode are both true, state it clearly. Dependencies are the silent killers of midnight fixes. A reader might fix the obvious part and never realize a hidden condition is blocking the whole chain.

The “Midnight Card” – An Emergency One-Pager

All the detail above is necessary, but it’s too much to digest during a crisis. Create a single page—digital and printed—that answers the most urgent questions. Store it near the main hub or breaker panel. It should include:

• Wi-Fi network name and password (guest network too, if devices use it)
• Hub or controller IP address and how to access it (app name, login URL)
• Which devices to reboot first if the system acts up (often the router, then the hub, then specific bridges)
• Phone numbers for the internet provider and any critical support contacts
• Location of backup power supplies (UPS, generator, battery packs)
• A short list of “If X happens, try Y” steps

This card is not a manual. It’s a triage tool. When the house goes dark and the app won’t connect, the card says: “Check breaker 14. If that’s on, unplug the black box labeled Hub 1 for 30 seconds. If lights still don’t work, use the physical switches.” That kind of direct instruction keeps people calm and functional.

Use Version Control (Even for a House)

Your setup changes. You add a sensor, retire a protocol, or move a hub. If the documentation doesn’t change with it, it becomes noise. Keep a change log at the bottom of your main document. Date each entry and describe what you changed and why. Example:

“2025-01-12: Replaced Zigbee outlet in office with Z-Wave model because of interference with Wi-Fi channel 6. Updated device inventory and affected automation #4.”

Store the documentation somewhere accessible without your primary login. A shared cloud folder, a printed binder, or a flash drive in a known drawer works. If the documentation lives only on your password-protected laptop and you’re unreachable, it’s useless.

Test the Documentation With a Real Person

The only way to know if your documentation works is to have someone else use it. Pick a friend or family member who isn’t familiar with your setup. Give them the documents and a scenario: “The living room lights won’t turn off. Find the problem using only these notes.” Watch where they get stuck. Update your documentation based on what confused them.

This test often reveals you’ve used insider terms. “The Z-wave dongle” means nothing to someone who doesn’t know Z-wave from a USB stick. Replace jargon with location and function: “The small USB device plugged into the back of the living room hub.”

Keep It Boring and Standard

I’m skeptical of gadget hype, and that extends to documentation tools. You don’t need a fancy wiki or a diagramming app for most home setups. A plain text file, a spreadsheet, or a shared document works fine. The format matters less than the habit of updating it. Use standard terms: “light switch,” not “in-wall relay actuator.” Use consistent names: if you call it “Porch Light” in the app, call it “Porch Light” in the document, not “Front Door Exterior.”

Also, document what you didn’t automate. A visitor might assume a switch is smart when it’s just a dumb switch that looks modern. Note any manual overrides or physical disconnects. If a lamp is on a smart plug but also has a physical switch that must stay on, say so.

Plan for Obsolescence

Systems age. A hub loses support, a company goes under, a protocol fades. Your documentation should note the “sunset date” for any device or service you know has a limited lifespan. If your hub requires a cloud account that might not exist in three years, write that down. The person fixing things at midnight in 2027 will thank you for the warning that the problem might be a dead backend, not a dead battery.

This future-aware mindset also means documenting the login credentials and recovery methods for every account tied to the system. Use a shared password manager or a sealed envelope in a fireproof safe. Don’t rely on your phone’s face recognition to be the only key.

Internal Resources to Help You Audit First

Before you document, you might need to audit what you actually have. Many small systems grow quietly until they’re a tangled mess. I’ve written about this process in more detail in How to Audit the Small Systems That Quietly Run Your Week. That guide walks through a full inventory method that pairs well with the documentation steps here.

Frequently Asked Questions

What’s the fastest way to start if I have zero documentation today?

Grab your phone and walk room by room. Take a photo of each smart device, then speak a voice memo describing its name, location, and power source. Transcribe those memos into a simple list. You can have a rough inventory in under an hour. The midnight card can be written in 15 minutes once the inventory exists.

Should I include wiring diagrams for hardwired devices?

Only if the wiring is non-standard or you’ve made modifications. A photo of the open junction box with labeled wires is often more helpful than a diagram. Store those photos in the same folder as your documentation. If you used a pro installer, ask for their notes and add them to your file.

How often should I update the documentation?

Every time you add, remove, or change a device or rule. Set a calendar reminder for a quarterly review. During that review, test a few automations and verify the midnight card is still accurate. Treat it like checking smoke detector batteries.

What if my system uses multiple apps and platforms?

Create a master list that maps each automation to its home platform. For example: “Morning lights routine: Apple Home app. Porch motion alert: Hubitat. Garage door close reminder: Home Assistant.” Note which app takes priority if there’s overlap. This prevents someone from changing a setting in the wrong place and breaking a chain.