Describing your app

The opening description does most of the work. You do not need technical vocabulary. You need to be specific about people, tasks and data.

Start with the job to be done

One sentence about who needs what:

• "A tool for our support team to log customer complaints and see who is handling them."
• "A site where members can book a desk for the day and see which desks are taken."

If you cannot say it in one sentence yet, the first version is probably trying to do too much.

Name the people

Most apps have two or three kinds of user. Name them and say what each can do:

• Visitors can browse and submit an enquiry, but not see anything else.
• Members can manage their own bookings.
• Staff can see everything and change any booking.

Those roles decide what each person sees, so getting them right early saves a rebuild later. See Roles and permissions.

List the things you keep track of

Say what a record looks like in plain language. "A client has a name, an email, a phone number and a list of sessions" is enough for the builder to create the right shape. If you already have a spreadsheet, describe its columns or paste a screenshot of the header row.

Describe screens in the order people use them

"First they see a list of open jobs. Clicking one opens the detail page with notes and a status dropdown. There is a button to create a new job from the list." That is a whole app in three sentences.

Say what should happen when things go wrong

The details that make software feel finished are usually the unhappy paths:

• What happens when a form is submitted twice?
• Can a booking be cancelled, and does the slot become available again?
• What should an empty list say?
• Who gets an email when something changes?

You do not have to cover all of them up front. Just know that they are part of the work, not polish.

A description that works

A membership site for a small gym.
Members sign in and see this week's classes, book a place,
and cancel up to two hours before the start.
Staff see each class with a list of who booked,
can add a member manually, and can cancel a class (members get an email).
No payments for now.

Next: Iterating in chat.