The brief that makes a web application project go well

One: who the users are, by type

Not how many, but how many kinds. A customer, an internal administrator and a read-only manager are three types, and each needs its own screens, permissions and testing.

The count of user types is one of the strongest predictors of effort, and it is usually underestimated because the second and third types feel like variations on the first until someone tries to build them.

Two: what each type may do

For each type, what they can see, create, change and delete. The interesting entries are the ones where the answer is "their own" — a customer sees their own orders, a manager sees their team's.

Those scoped permissions are a design decision that reaches through the whole data model, and discovering one late usually means revisiting queries written on the assumption it did not exist.

Three: the data you already have

Most applications are not starting from nothing. There is a spreadsheet, an old system, an export from something. What exists, in what format, how clean, and whether it has to come across.

Migration is routinely treated as a last-week task and is routinely the thing that overruns, because real data contains cases the new model did not anticipate. Naming it in the brief gets it estimated rather than absorbed.

• User types and what each may do, including anything scoped to "their own"
• Existing data: where it lives, what shape it is in, whether it migrates
• Systems to integrate with, and whether each has a usable API
• Realistic volumes: records, users, concurrent use at the busiest moment
• What must be true for this to be considered done
• What is explicitly not in scope for version one

Four: integrations, and whether they are actually possible

Every application brief names systems it should talk to. The question that matters is whether each has an API you can use, with credentials you can obtain, documented well enough to build against.

Sometimes the answer is no, and the integration becomes a file exchange or a manual step. Far better to establish that in week one than in the week before launch, because it changes what the application is.

Five and six: volumes, and the definition of done

Volumes separate a straightforward build from one that needs attention to performance. A thousand records is a different application from ten million, and twenty concurrent users is different from two thousand at nine on a Monday.

The definition of done is the one that prevents the longest arguments. Written as observable outcomes — this person can complete this task, this report balances against that system — it tells everyone when version one is finished. Without it, scope grows by a feature a week, each individually reasonable.

Questions we get asked