Logo

Templates

Written April 28, 2023 by Jonathan De Groot

Successful project requirements clearly and concisely communicate user needs amongst delivery teams. Many organizations use different formats for their requirements to best suit their audience and intent. Ensuring you are communicating in a consistent and effective manner can ensure your entire organization is able to deliver faster and with less confusion.

This article's aim is to demonstrate how Requiremint can assist and empower you and your team to create well-defined requirements with the use of templates.

Table of contents

If these common formats do not fit the needs of your organization or project Requiremint also offers a custom templating feature where you can input a custom template tailored to your needs. You can learn more in the  Custom Template  article.

How To Use Requiremint Templates

Requiremint will restructure the content and adjust language for better clarity and understanding. The templates can be found once logged into Requiremint and text has been entered into the editor by clicking the "AI Reformat" button to view a dropdown of requirement formats supported:

Upon successfully login requirement users will be able to enter their requirement text into the editor. From here there is an “AI Reformat” button. After clicking on the “AI Reformat” button a dropdown will appear displaying the supported templates. Upon selecting a dropdown option a popup modal will appear and preview what your requirement text would look like. If satisfied click the “Accept” button to update the editor with the proposed changes otherwise click the “Reject” button.

Bank Withdrawal Scenario

In order to illustrate the different formats Requiremint supports we will use the example of a customer withdrawing cash from a bank machine as a basis to explore how different templates can be used to help create familiarity and increase clarity when crafting your requirements below.

Gherkin

Gherkin is a syntax used for writing executable scenarios for behavior-driven development (BDD) and is used in tools like Cucumber. The syntax has a specific structure consisting of keywords and natural language statements.

The following is an example of a Gherkin scenario:

    Feature: Bank Machine Withdrawal

    Scenario: Successful withdrawal of cash from bank machine

    Given the customer has a valid bank card
    And the customer is at an bank machine
    When the customer requests to withdraw a specific amount of cash
    And the customer enters their PIN
    And the bank machine processes the withdrawal request
    Then the bank machine should dispense the requested cash amount
    And deduct the amount from the customer's account balance
    And provide a receipt for the transaction
    And return the customer's bank card

In this example, the scenario describes a successful withdrawal of cash from a bank machine. It follows the Gherkin syntax of given-when-then, with each scenario including a set of given conditions, a set of actions, and a set of expected outcomes.

Gherkin syntax is popular because it clearly states each trigger and expected result. By listing each condition on a new line, readers can easily track each function in the process.

References: https://cucumber.io/docs/gherkin/reference/

Bug

Bug templates are used for reporting bugs or issues in software development. The syntax of a bug template is designed to provide a consistent format for describing the problem, including steps to reproduce it, expected behavior, and actual behavior.

The following is an example of a Bug scenario:

    Bug Report:
    Unable to withdraw cash from bank machine

    Steps to reproduce:
    1. Insert bank card into bank machine
    2. Enter PIN
    3. Select withdrawal option
    4. Enter withdrawal amount
    5. Press "Enter" to confirm withdrawal
    6. Receive message "Transaction cannot be completed"

    Expected Result:
    The bank machine should dispense the requested amount of cash to the bank customer, providing quick and convenient access to their funds.

    Actual Result:
    The bank machine did not dispense the cash and showed a message stating that the transaction could not be completed.

Bug reports are very effective when the actual result does not align with the expected result. The steps to reproduce also provide a clear guide so bugs can be simulated and solutions are properly tested before the bug is considered resolved.

References: https://orangesoft.co/blog/how-to-write-a-bug-report

User Story

The user story template is a widely used approach to capture software requirements in a concise and user-focused way. It consists of three key elements:

  1. The user refers to the person or group of people who will use the product or feature being developed.
  2. The action describes what the user wants to do or achieve.
  3. The goal describes the expected outcome of the action.

User stories are a simple and effective way to capture the requirements from the end user's perspective and focus on delivering value to them. There are a variety of approaches to taking a user story and breaking it down into a requirement.

The following is an example of a user story that has been broken down and extended into a template by including Gherkin syntax within the scenario and acceptance criteria:

"As a bank customer, I want to withdraw cash from a bank machine, so that I can have access to my funds quickly and conveniently."

    Feature: Bank Machine Withdrawal

    Scenario: Successful withdrawal of cash from bank machine

    Given the customer has a valid bank card
    And the customer has sufficient funds in their account
    When the customer inserts their card into the bank machine
    And selects the option to withdraw cash
    And enters the amount they wish to withdraw
    Then the bank machine dispenses the requested amount of cash
    And the customer's account is debited by the amount withdrawn

    Acceptance Criteria:

    • The customer must have a valid bank card
    • The customer must have sufficient funds in their account to withdraw the requested amount
    • The bank machine must dispense the correct amount of cash requested by the customer
    • The customer's account must be debited by the amount withdrawn from the bank machine

User Stories provide context and more explicit information, but are less brief than other formats. Often used as a historical record or in organizations where lots of supporting information has to be provided in the requirement.

References: https://www.atlassian.com/agile/project-management/user-stories

Use Case

The use case syntax is a way of capturing the functional requirements of a system. It typically consists of a description of a specific action or task that the system must perform, along with any relevant actors and pre- and post-conditions.

The following is an example of a use case scenario:

    Use case:
    Withdraw Cash

    Actors:
    Customer, Bank machine

    Pre-conditions:
    The customer has a valid bank machine card and PIN, bank machine has cash available

    Description:
    The customer inserts their bank machine card into the machine and enters their PIN. They then select the "Withdraw" option and enter the desired amount. The bank machine dispenses the cash and updates the customer's account balance. The customer takes the cash and their card and the transaction is complete.

    Post-conditions:
    The customer has received the requested amount of cash, and their account balance has been updated. The bank machine cash balance has decreased by the amount withdrawn.

Use Cases can often be easily distilled from User Journeys and help map a user's flow during an interaction. A strength of the use case template is it can be strung together to form a complete path, a process that can identify requirement gaps as well.

References: https://blog.logrocket.com/product-management/what-is-a-use-case-template-how-to-write/

Go back to the top of the page