Organised by task, not by tool

We published a use-case library this week: 65 pages, one per task a team can actually get done across their connected tools.

The pages themselves are straightforward. The decision worth writing about is the one that shaped them, which was refusing to organise the library the way this kind of library is normally organised.

The default is to file by tool

Almost every integration platform sorts its examples by connector. You arrive, you find your tool, you see what it can do. It is an easy structure to build, because it falls straight out of the catalog you already have, and it is an easy structure to grow: a new integration means a new page, automatically.

It also has an obvious search logic behind it. People do type tool names.

We had that structure already. Our integrations directory files 175+ tools exactly this way, and it works — for the question it answers.

The problem is that it answers "what can this tool do?" and almost nobody's actual problem is shaped like that.

Nobody has a Notion problem

The person who needs this is not wondering what Notion can do. They know what Notion can do; they use it every day. What they have is a Tuesday-morning problem: sixty tickets and no order to them, a launch that happened and numbers in three dashboards, a design thread that everyone agreed on and nobody turned into tickets.

Those are not tool problems. Each one sits between tools, which is precisely why it is still being done by hand — no single vendor has an incentive to fix a workflow that leaves their product halfway through.

Filing by tool hides exactly that. A task spanning Sentry, GitHub, and Slack has no home in a tool-shaped library; it gets filed three times, or once and arbitrarily, and either way the reader who has that problem has to already know which tool to look under to find the answer to a question that spans all three.

So the unit is the task

Every page in the library is named for an outcome, not a connector: triage the support queue, ship the latest commit, turn a design into tickets, reconcile payouts. The integrations appear as ingredients partway down.

This is harder to build. There is no generator that produces a task list from a catalog — someone has to decide which tasks are real, and be wrong sometimes. It also grows less automatically: a new integration does not create a new page, it quietly makes a few existing pages more useful.

The trade is worth it because the pages now match how the problem arrives. Someone with the Tuesday-morning problem can find the page for it without first working out which of their four tools is the "main" one.

What it changed about the writing

Two things, both unexpected.

The first is that a task-shaped page cannot hide behind capability language. A tool page can say "supports issue creation" and be finished. A task page has to say what happens first, what happens next, and what you end up holding — and if you cannot write the last one, you do not have a task, you have a feature.

The second is that it forced honesty about scale. Once tasks were the unit, we could count what they actually used, and the answer was smaller than we expected: a median of two tools and four steps per task. Under a tool-shaped structure we would never have known, because the structure would have had nothing to say about it. We wrote up the full count in Sixty-five tasks, forty-one tools.

The part we are still unsure about

Tool-shaped pages have a real advantage we gave up: they match what people type. "Notion integration" is a search; "turn a design into tickets" is a description of a feeling.

We think that is changing — more people now describe the outcome they want rather than the tool they want it in, which is the same shift that makes an assistant useful in the first place. But we are not certain, and the honest position is that the two structures answer different questions and we now maintain both.

If you have the Tuesday-morning problem, the use-case library is the one to start from. If you have a tool and want to know what it can reach, the integrations directory is still there, and it is not going anywhere.