All notes

The Tool That Explains Itself Is Already Failing

Good tools don’t need tutorials.

That sounds extreme, so here’s the sharper version: the moment a tool requires a tutorial to complete its primary function, it has already failed at its primary function.

This isn’t about simplicity for its own sake. Complex work exists. Complex tools sometimes follow. But there’s a difference between complexity that mirrors the actual problem and complexity that lives inside the software for no reason the user can trace.

When a tool ships with a “Getting Started” guide that runs fifteen pages, someone made decisions. Those decisions just happened in documentation instead of design.

The test Scott Andrew Alpaugh uses is blunt: hand the tool to someone who understands the domain but has never seen the interface. If they can’t orient themselves in under two minutes, the tool is carrying debt — and it’s spending that debt on the user’s time.

The best tools make the right action obvious. Not because they’re simple, but because whoever built them understood the work deeply enough to know what the user needs next before the user has to ask.

Explanation is a tax. Every onboarding doc, every tooltip, every help ticket is a charge against a design decision that wasn’t finished.

The goal isn’t zero documentation. The goal is a tool that makes you reach for the documentation less every week — until you stop reaching at all.

That’s when you know the tool fits the work.