Tooling for people standing in a basement
Installing our hardware lived in a binder and in four people’s heads. I turned it into ten guided flows in six weeks, seven of them in one afternoon.
The instructions aren’t what made it work. The gates are.
Why a missed step is expensive
Getting a building onto Runwise means somebody installs a control box, a modem, and a set of sensors.
A missed step doesn’t announce itself. A sensor goes on the wrong pipe, everybody drives away happy, and six weeks later the building looks twelve degrees colder than it is.
Now you send a truck back out. That is the most expensive thing that happens in this business.
My role
I designed all ten flows, built a working version of one myself, and wrote front-end code for the rest.
Not mine: the install program. I didn’t hire or train anybody or touch the hardware, and the numbers at the bottom come from all of that moving at once.
Who is holding the phone
Field ops named the three things that made this hard. I’d have gotten all three wrong on my own.
- The knowledge was tribal, so people learned by shadowing.
- The installer is often a contractor doing one of these a month, who won’t remember last time and won’t read documentation.
- He’s in a mechanical room at 7am with cold hands.
If you remember one thing about who this is for, it’s that he has one free hand.
One flow per device, which sounds dumb
The obvious move is a single clever wizard that handles every device. I didn’t do that.
Clamping a sensor onto a hot pipe and screwing one to an outside wall have almost nothing in common.
A single wizard has to invent shared wording that fits neither. That cost doesn’t land on me.
It lands on the guy working out whether “position the unit” means the thing he’s looking at.
So ten flows. More work for me, less for him.
The first three took two weeks because we were settling the grammar: how a step gets framed, where confirmation lives, what failure looks like.
Once engineering and I agreed on that, I posted seven more in an afternoon.
Introducing the gates
An instruction is not a mechanism.
You can tell somebody what to do and they might do it. If you make them show you, then you know.
So four things the software won’t let you walk past:
- Placement gets checked against stated criteria, not your judgment.
- Power-on gets confirmed by reading the light on the device, which the app can’t fake for you.
- A photo of the finished unit is required. Cheapest audit trail there is.
- A live roster, so “am I done” is a screen and not a memory.
Plus check-in procedures we wrote with field ops that surface a failure while somebody is still in the building.
Two hours in a boiler room
I decided all of that at a desk, which is not a great way to be confident about a boiler room.
So for the wireless sensor I built a working version at a real web address, filled it with fake data, and sent the links to the field team.
Che, one of our technicians, ran it live during an actual install while I stayed out of it.
Fifteen minutes a sensor. A full boiler room in about two hours. I was expecting a list of problems. His entire review was “nothing confusing.”
I’d rather have that than a compliment. Nobody has ever said a nice thing about an install flow.
The nine flows before that one
I designed nine of these before I’d ever stood in a mechanical room during an install.
I had documentation, engineering input, and field ops on every review. None of that is the same as watching a contractor do it at 7am.
They were good enough to ship. They’d have been better after one morning of watching.
So I changed the order I work in.
Field validation is something I schedule at the start now, and that’s the only reason the wireless sensor went out as something Che could click.
Still on the list: I never tested any of it with gloves on. Thought about it, said I would, didn’t.