Clarifying requirements

A visitor walks up to a library desk and asks for something good to read. A careful librarian asks questions before reaching for a book. They ask who the book is for, what the visitor enjoyed last, whether it is for tonight or for a holiday next month, and whether anything is off limits. Five minutes of questions turn a vague wish into a request the librarian can fill well.

A request to build an ML system deserves the same treatment. A line such as suggest books could mean helping a reader find their next book or helping a shop decide what to stock, and the two need different inputs and produce different results. Start with the person using the feature and what they are trying to do, then describe what happens when they use it, from the information they provide to the result they receive. Three things settle the first part.

A broad feature grows into several separate problems unless someone draws a line around it. For book suggestions, the design might include recommendations based on books a reader has rated, and leave book search and written reviews outside. Say the boundary out loud so the rest of the discussion stays on one problem.

Missing information should stay visible instead of being filled in without anyone noticing. If the request does not say whether new readers with no ratings need suggestions, ask. If nobody can answer, write down the assumption you will use, such as showing new readers a general list, and say what would change if the assumption turns out to be wrong. An assumption that is written down can be checked later, and one that stays silent becomes a surprise.

Boundaries also tell you what the first version must not attempt. If written reviews were inside the line, the design would need a second kind of model that reads text, and the feature would wait for both models to be finished. Leaving reviews outside lets the ratings-based list ship on its own and gives the team a working feature to learn from.

The librarian can ask a follow-up question whenever the first answer is unclear. A system cannot, so every ambiguity the librarian would have resolved in conversation has to be resolved now, in the requirements, before the system exists.

Knowing the desired result is half the problem. The other half is what information exists to produce it and the conditions the system must work under. At this stage, name the limits with numbers where you can and leave the question of how to meet them for later.

Bring the answers together before moving on. A useful statement names the person, the input, the output and the main boundaries in a few sentences, and keeps confirmed requirements apart from assumptions and from questions that still have no answer.

For the library, the agreed statement might read as follows. When a reader opens the home page, the system suggests up to ten books that are available to borrow, using the books that reader has rated before. Readers with no ratings receive a general list of popular books. Book search and written reviews are outside this design. We still need to confirm the expected traffic and the response deadline.

A table keeps the three kinds of statement apart, so a reviewer can see at a glance what is settled and what is still open.

Two confusions are common here. People mistake the request for the need, and set out to build what was asked for instead of what would help, which is why the first section begins with the reader and the shop manager. People also accept words like fast and accurate as requirements, when only a number can be tested, and a design that promised fast can never be shown to have failed or succeeded.

The statement gives us a specific feature to design without choosing a model too early. The next topic explains how to turn the goal of helping a reader into a task a model can learn, and how to measure whether the feature helped.