Tooling for people standing in a basement

Getting a building onto Runwise meant somebody installed a control box, a modem, and a set of sensors. The process lived in a binder and in four people’s heads. I spent six weeks turning that into ten guided flows. Seven of them in one afternoon.

And to be clear, the speed is not the story I want to tell. I started by writing better instructions, then realized instructions were never the expensive part.

The expensive part was finding out, six weeks later, that a step had been skipped.

I started with the wrong problem

The project began with one sentence, which I now think is a pretty good brief and a very easy one to misread:

Runwise field technicians and third-party installers do not have a clear, uniform process for how to conduct our installs and document them.

I read that as an instruction problem. Better steps, clearer language, one device at a time. I would have shipped a nicer binder.

The important words were “document them.” Instructions tell someone what to do. Documentation tells the rest of the company what actually happened. Our expensive failures came from learning too late that the two were not the same.

One free hand

The field team gave me the constraints I would have missed at a desk. The knowledge was tribal, so people learned by shadowing. The installer was often a contractor doing one of these a month, who would not remember last time and would not read documentation. And they were in a mechanical room at 7am, often cold, holding the device they were installing.

If you remember one thing about who this is for, it is that they have one free hand.

That changed the shape of the product. Every screen needed one job. Every instruction had to sit next to the thing it described. And the critical steps had to stop the flow until the installer supplied evidence.

A mistake can stay quiet for six weeks

Put one sensor on the wrong pipe and everybody can leave happy. Six weeks later the building looks twelve degrees colder than it is. Then Runwise sends another truck and another technician to discover something that could have been fixed in five minutes.

That return visit can cost more than the original install. The problem was not only helping someone do the work. It was finding mistakes while they were still standing next to them.

Ten guides, because the hardware is actually different

A single guide for every device sounded efficient. It was also a way of making the installer do my job. Mounting a sensor on a hot pipe and attaching one to an outside wall are not versions of the same instruction. Shared wording like “position the unit” would have forced the installer to decide whether it applied to the object in their hand.

So I designed ten. Every one started by identifying the device and ended with a photo. The middle changed: a gas sensor needed verification, installation, and testing; a riser sensor needed almost nothing; a toilet sensor needed help locating the unit and closing the clasp.

The first three took two weeks. We were not drawing three guides so much as agreeing on the system underneath them: instruction, confirmation, failure. Once that structure held, I designed seven more in one afternoon.

And to be honest, I could have collapsed the three pipe-mounted devices into one flow. I did not have a principled reason for keeping them separate. Separate felt clearer while I was drawing them, and by then another guide was cheap.

The software was allowed to say no

Most checklists are polite. You can tap past them and keep going. These were deliberately less helpful.

If the placement was not confirmed, the flow stopped. If the installer had not read the light on the physical device, it stopped. If there was no finished photo, it stopped. The delay was the feature. A person still in the room can fix the work. A person who left six weeks ago cannot.

The queue in the basement

The phone could collect perfect evidence and still lose it. Installs happened below street level, where a queue might sit offline until the connection returned.

This is one of those details that looks like engineering and is actually the product. A non-200 response meant the server rejected one transaction — a duplicate, a stale ID — so the other nine devices somebody just installed could still go up. A thrown request meant the network or the client had fallen over, and the code treated that as evidence the whole flush was doomed rather than burning the queue against a dead connection.

Both produced the same red toast. Simple for the technician. Hidden underneath: one device failed, or everything behind it was still waiting. Individually that is a small decision. Together with the checkpoints, it is the difference between a tool that records work and a tool that can lose it.

Two hours in a boiler room

I had designed the first versions at a desk. For the wireless-sensor guide, I built a working prototype and asked Che, one of our technicians, to use it during a real installation without my help.

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.

Che, Runwise field technician

I love that this is the review. For a tool meant to disappear into physical work, “nothing confusing” is the result I wanted.

The test I should have run first

I designed nine of the ten guides before I watched an installation in a mechanical room. I had documentation. I had reviews with the people who ran the field team. Those things were useful, and they were not a substitute for seeing the work.

The guides were good enough to ship. One morning in the field would have made them better. I now schedule that kind of observation at the start of a project, before a clean interface makes the problem look cleaner than it is.

There is one more loose end: I never tested the flows with gloves on. I thought about it, said I would, and did not.

The pattern kept working without me

The strongest evidence came after I stopped working on the project.

Runwise later gave the same guides directly to customers when a technician could not enter every apartment. The guides did not need to change because they had never assumed expert knowledge.

The pattern spread to gas sensors, then to a toilet-leak sensor customers could install without Runwise technical support at all. Requiring proof at each important step made it safer to hand the work to someone without specialized training.

That is the part I am proudest of. The product kept working when the original team, the original technician, and eventually the designer were no longer in the room.

The bigger picture

What I want you to take from this is not that software saved $300K. The program did that: hiring, training, hardware, and the tooling together. Claiming the flows produced every dollar would turn a good result into a bad argument.

What the software did was make the work prove itself. Once that was true, it did not matter as much who was holding the phone. The product kept working when the original team, the original technician, and eventually the designer were no longer in the room.

I designed all ten flows, built a working version of one, and wrote front-end code for the rest. I did not run the installation program, hire or train the technicians, or design the hardware. These numbers belong to that whole program.

There is still a loose end I think about. I never tested the flows with gloves on. I thought about it, said I would, and did not.