Describing what you need

The single skill worth learning here. Everything else in this documentation is mechanics.

Say what it is for#

The most useful sentence you can write is the one about the person using it.

Vague — Add a filter to the list.

Useful — Salespeople are scrolling past everybody else's proposals to find their own. They should see theirs first, with a way to see everyone's.

The second says what problem is being solved, which means the builder can solve it properly instead of adding exactly the control you named and no more.

Be concrete about records and fields#

When you are describing something the application should keep track of, name the fields. This is not being technical — it is being specific.

Each site visit has a date, an engineer, a customer, a short report and up to six photographs. Visits can be marked complete. A visit that is not complete after three days should stand out on the list.

That produces the right thing first time. "A tool for site visits" does not.

One thing per message#

Three separate messages beat one message with three requirements, for a reason that shows up later: when something comes back wrong, you know which request caused it, and you can go back to the version before it.

The exception is when two changes genuinely belong together — add a note field, and show it on the detail page is one thought.

Say what is wrong, not what to do#

You are the person who can see it. The builder is the person who can change it.

Works — The dates are unreadable on a phone; they wrap onto three lines.

Works less well — Set the date column to white-space: nowrap.

The first describes a problem you can actually see and lets it be fixed properly. The second is a guess at an implementation, and if it is the wrong guess you get the wrong fix.

Prefer a setting to a request#

Some things are settings rather than code, and asking for them as code means the next build can undo them:

• the browser tab title and the icon
• what a link to it looks like pasted into a message
• redirects from old addresses
• what search engines are told
• values like an API key or an account number

All of these live in Settings, apply on every deployment, and cannot be overwritten by a build. See Running it. You can still ask for them in the conversation — the builder will put them in Settings rather than in the code.

Things it cannot do#

Said plainly so you do not spend an afternoon rephrasing:

• A different framework or language. Every application here is built the same way. This is the constraint the whole platform rests on.
• A service we have not connected. Email, SMS and Google are built in. Anything else has to be an ordinary HTTP API called with a key you put in Settings.
• Reading from a database somewhere else, unless it is reachable over the internet and has an API.
• A native mobile application. An application can be installed to a phone's home screen and behave like one, but it is a web application.

Worked examples#

Starting from nothing

A register for our loan equipment. About 200 items — laptops, projectors, cameras. Each has an asset tag, a name, a condition and a location. Staff borrow an item by scanning or typing the tag; it records who has it and when it is due back. Facilities need a list of what is overdue, and to see the history of any item.

Changing something

On the overdue list, show how many days overdue rather than the due date. Sort by that, worst first.

Fixing something

When I save a visit with no photographs it says "Saved" but the visit does not appear in the list. It only appears after I reload.

Asking for a judgement

This list is going to have 5,000 rows by next year. Is it going to be usable? Do whatever you would do to make that fine.