Handee, the compliance system we build for multi-site property operations, now greets a new customer with a setup checklist. Our first version of it contained a step the customer could not complete, no matter what they did.
We found it before it shipped, fixed it, and then found the same fault twice more in the same release. Neither of the later two looked anything like the first.
A step that waits on a stranger
The step asked a facilities manager to review a quote, and it ticked when a contractor submitted one.
Read it as a sentence and it is unarguable. Reviewing quotes is obviously part of learning the product. Read it as a condition and it is somebody else's decision. A manager who added her sites, raised a job and sent it to the right firms, and then drew no bids, would have sat at four of five for as long as she owned the account, having done every part of her own job correctly.
The instinct is to move the step further along. It does not survive contact: awarding a quote needs a quote, and approving an invoice needs a supplier to bill you. Every candidate further down the process hands the finish line to a third party.
So we changed what the step asks. It now asks the customer to find the page where quotes arrive, which is useful before the first quote exists and never depends on anyone else.
The second one, and the third
Having written the rule down, we went looking, and found it one floor below the room we had just cleaned.
The invoice inbox carried its own small list of suggested actions: open an invoice, filter by variance. Both need an invoice, and an invoice exists only when a supplier bills you. A customer who had finished every item on the checklist we had just corrected could open that page and meet two suggestions with no way to clear either.
The third one passed the test we had written. On the contractor side, a step ticked when the contractor submitted a quote. Their action, on their own record, which is exactly what we had told ourselves to check for. But a contractor can only quote a request that an operator chose to send, so a contractor who completed a listing, published it and uploaded a certificate still stopped at three of four indefinitely.
The rule we had written asked whose record the software reads. It should have asked whose action has to happen first.
The counter-case is what keeps the rule usable. The request-for-quote list starts empty for every new customer, and we left its suggestions alone, because the operator's own dispatch fills it. The test is whether the customer's next move can fill the page.
What we did instead of a checklist item
Two things, and only one of them was code.
The rule is written out in full where the deleted step used to be, in the file a future engineer will have open when they are tempted to add the next one. A wiki would have said the same thing in a place nobody reads at the moment they need it.
The second is a step we built, finished, and then deleted. It asked contractors to invite a colleague. Everything it needed already existed, it worked, and it would have been hidden from anyone without permission to send invitations. We removed it because a large share of the contractors on the platform are sole traders, and the step asks them to recruit somebody in order to clear a box.
That is a different question from the one we had been asking. Can the customer finish this alone is necessary. Do they have any reason to is the one that decides whether a checklist is help or homework, and no permission check can answer it.
Why any of this should matter to you
Every supplier who demos software to you will show you an onboarding checklist going green. Almost all of those checklists count clicks. The number tells you how well the demo was rehearsed, and it will read one hundred per cent for an account nobody has ever done real work in.
There are two questions worth asking of any progress bar a supplier puts in front of you. Does anything on it depend on a third party doing something? And can I tick any of it without having done the thing it describes? Both are cheap to ask and neither is usually prepared for.
Every supplier will also tell you they fixed the bug you found, and fixing it is the least of what happened. The useful thing to know is what they did in the hour afterwards: whether they asked what class of mistake it was and went looking for the rest of it, or whether they closed the ticket.
We asked, and it cost us two more findings and a step we had already built. A supplier who cannot name the class only ever found the instance.
The number we promise clients is the human time recovered on the work they hand us. A checklist that lies about progress is small, and it inflates a number nobody goes back and checks, which is why the two we found after the first are in this post. The version written for the operators and contractors who use the product is on the Handee site.