Specifying Requirements

A textual description (i.e., prose) can be used to describe requirements. Prose is especially useful when describing abstract ideas such as the vision of a product.

Avoid using lengthy prose to describe requirements; they can be hard to follow.

A common format for writing user stories is:

You can write user stories using a physical medium or a digital tool. For example, you can use index cards or sticky notes, and arrange them on walls or tables. Alternatively, you can use software (e.g., GitHub Project Boards, Trello, Google Docs, ...) to manage user stories digitally.

User stories in use

With sticky notes

^{[credit: https://www.flickr.com/photos/jakuza/2682466984/]}

---

With paper

^{[credit: https://www.flickr.com/photos/jakuza/with/2726048607/]}

---

With software

^{[credit: https://commons.wikimedia.org/wiki/File:User_Story_Map_in_Action.png]}

---

---

The {benefit} can be omitted if it is obvious.

It is recommended to confirm there is a concrete benefit even if you omit it from the user story. If not, you could end up adding features that have no real benefit.

You can add more characteristics to the {user role} to provide more context to the user story.

You can write user stories at various levels. High-level user stories, called epics (or themes) cover bigger functionality. You can then break down these epics into multiple user stories of normal size.

You can add conditions of satisfaction to a user story to specify things that need to be true for the user story implementation to be accepted as ‘done’.

These are more widely known as acceptance criteria. Whatever they are called, they are the part of a story that states an observable result, and therefore the part that survives when the conversation behind the story does not.

Other useful information that can be added to a user story includes (but is not limited to):

• Priority: how important the user story is
• Size: the estimated effort to implement the user story
• Urgency: how soon the feature is needed

User stories capture user requirements in a way that is convenient for , , and .

[User stories] strongly shift the focus from writing about features to discussing them. In fact, these discussions are more important than whatever text is written. _{[Mike Cohn, MountainGoat Software 🔗]}

User stories differ from mainly in the level of detail. User stories should only provide enough details to make a reasonably low-risk estimate of how long the user story will take to implement. When the time comes to implement the user story, the developers will meet with the customer face-to-face to work out a more detailed description of the requirements. [more...]

Leaving out detail on purpose relies on the implementer being able to come back and ask. Where asking is slow or does not happen at all — work handed to another team across a time zone, or generated in a single pass by an AI coding assistant with no round of clarification — an unstated detail never surfaces as a question. It gets filled in with a plausible guess, and the guess arrives faster than the question ever would.
Example 'As a user, I can delete a task' leaves open whether deleting is recoverable. Someone who can ask, asks. Someone working from the story alone picks one, and the answer looks finished either way.

The further the implementer sits from the conversation, the more of a story's meaning has to survive in writing — which is the job the acceptance criteria are doing.

User stories can capture non-functional requirements too because even NFRs must benefit some stakeholder.

While user stories can be recorded on in the initial stages, an online tool is more suitable for longer-term management of user stories, especially if the team is not .

A use case describes an interaction between the user and the system for a specific functionality of the system.

System: Online Banking System (OBS)
Use case: UC23 - Transfer Money
Actor: User
MSS:
  1. User chooses to transfer money.
  2. OBS requests for details of the transfer.
  3. User enters the requested details.
  4. OBS requests for confirmation.
  5. User confirms.
  6. OBS transfers the money and displays the new account balance.
  Use case ends.

UML includes a diagram type called use case diagrams that can illustrate use cases of a system visually, providing a visual ‘table of contents’ of the use cases of a system.

In the example on the right, note how use cases are shown as ovals and user roles relevant to each use case are shown as stick figures connected to the corresponding ovals.

Use cases capture the functional requirements of a system.

A use case is an interaction between a system and its actors.

Actors in Use Cases

A use case can involve multiple actors.

An actor can be involved in many use cases.

A single person/system can play many roles.

Many persons/systems can play a single role.

Use cases can be specified at various levels of detail.

While modeling user-system interactions,

• start with high level use cases and progressively work toward lower level use cases.
• be mindful of which level of detail you are working at, and do not mix use cases of different levels.

Writing use case steps

Extensions are "add-ons" to the MSS that describe exceptional/alternative flows of events. They describe variations of the scenario that can happen if certain things are not as expected by the MSS. Extensions appear below the MSS.

Example Some extensions added to the use case in the previous example:

System: Online Banking System (OBS)
Use case: UC23 - Transfer Money
Actor: User
MSS:
  1. User chooses to transfer money.
  2. OBS requests for details of the transfer.
  3. User enters the requested details.
  4. OBS requests for confirmation.
  5. User confirms.
  6. OBS transfers the money and displays the new account balance.
  Use case ends.

Extensions:
  3a. OBS detects an error in the entered data.
      3a1. OBS requests for the correct data.
      3a2. User enters new data.
      Steps 3a1-3a2 are repeated until the data entered are correct.
      Use case resumes from step 4.

  3b. User requests to schedule the transfer for a future date.
      3b1. OBS requests for confirmation.
      3b2. User confirms future transfer.
      Use case ends.

  *a. At any time, User chooses to cancel the transfer.
      *a1. OBS requests to confirm the cancellation.
      *a2. User confirms the cancellation.
      Use case ends.

  *b. At any time, 120 seconds lapse without any input from the User.
      *b1. OBS cancels the transfer.
      *b2. OBS informs the User of the cancellation.
      Use case ends.

Note that the numbering style is not a universal rule but a widely used convention. Based on that convention,

• either of the extensions marked 3a. and 3b. can happen just after step 3 of the MSS.
• the extension marked as *a. can happen at any step (hence, the *).

When separating extensions from the MSS, keep in mind that the MSS should be self-contained. That is, the MSS should give us a complete usage scenario.

Also note that it is not useful to mention events such as power failures or system crashes as extensions because the system cannot function beyond such catastrophic failures.

In use case diagrams you can use the <<extend>> arrows to show extensions. Note the direction of the arrow is from the extension to the use case it extends and the arrow uses a dashed line.

You can use actor generalization in use case diagrams using a symbol similar to that of UML notation for inheritance.

Example Actor Blogger can do all the use cases the actor Guest can do, as a result of the actor generalization relationship given in the diagram.

Do not over-complicate use case diagrams by trying to include everything possible. A use case diagram is a brief summary of the use cases that is used as a starting point. Details of the use cases can be given in the use case descriptions.

Some use ‘System’ as an actor to indicate that something is done by the system itself without being initiated by a user or an external system.

Example The diagram below can be used to indicate that the system generates daily reports at midnight.

However, others argue that only use cases providing value to an external user/system should be shown in the use case diagram. For example, they argue that view daily report should be the use case, while generate daily report should not be shown in the use case diagram because it is simply something the system has to do to support the view daily report use case.

You are recommended to follow the latter view (i.e., not to use System as a user). Limit use cases to modeling behaviors that involve an external actor.

UML is not very specific about the text contents of a use case. Hence, there are many styles for writing use cases. For example, the steps can be written as a continuous paragraph.

Use cases should be easy to read. Note that there is no strict rule requiring you to write all details of all steps or to use all the elements of a use case.

There are some advantages of documenting system requirements as use cases:

• Because they use a simple notation and plain English descriptions, they are easy for users to understand and give feedback.
• They decouple user intention from mechanism (note that use cases should not include UI-specific details), allowing the system designers more freedom to optimize how functionality is provided to a user.
• Identifying all possible extensions encourages us to consider all situations that a software product might face during its operation.
• Separating typical scenarios from special cases encourages us to optimize the typical scenarios.

One of the main disadvantages of use cases is that they are not good for capturing requirements that do not involve a user interacting with the system. Hence, they should not be used as the sole means to specify requirements.

Specifying a term in the glossary is useful in the following cases:

• A domain-specific/technical term that may not be known to all stakeholders, to indicate its definition
• When a term has multiple meanings, to indicate which of them is used in the project
• When there are multiple terms used for the same concept, to indicate which of them will be used in the project

A supplementary requirements section can be used to capture requirements that do not fit elsewhere. Typically, this is where most Non-Functional Requirements will be listed.

Teams package these formats in different ways: some collect them into a single document that says what is to be built, while others keep each format where it is most useful and write down only what needs agreeing.

Where there is such a document, product-led teams usually call it a product requirements document (PRD), or a product brief. It typically carries the product's purpose, who it is for, the scope and the priorities within it, the stories or use cases that matter most, and the quality constraints the product has to meet.

A software requirements specification (SRS) is its more formal counterpart, used where requirements have to be agreed precisely with a customer, audited, or contracted for. An SRS is heavier, more structured, and more stable than a PRD; the two are not interchangeable names for the same thing.

A single document is one common packaging, not a rule. Many teams keep user stories in a tracker, the glossary in a wiki, and prototypes in a design tool, and write down only what needs agreeing in one place.

Each format earns its place by doing a different job:

• Prose frames the problem and the product's purpose.
• A feature list supports scope and delivery discussions.
• A user story records one negotiable slice of user value.
• A use case makes one workflow, and what can go wrong in it, precise.
• A glossary settles what shared terms mean.
• Supplementary requirements capture what cuts across all of the above.

Choosing between them is a question of what you need to be precise about, not of which notation is better.

Working from such a document has a name: specification-driven development means starting from a specification that is clear, versioned, and testable, and using it both to direct the implementation and to judge what comes back. The second half is the part that is easy to skip. A specification that only ever directs work, and is never used to check the result against, is a wish list.

This matters more as producing a candidate implementation gets cheaper. An assistant can draft questions, propose alternatives, or write code, but it cannot establish what stakeholders actually want, and it cannot decide a trade-off between things two of them both want. Those stay with the people accountable for the product, which is why writing the specification, and the judgment that goes into it, is the part of this work that does not get handed off.