In this section, you should describe all kinds of requirements for your module: functional and non-functional requirements.
Create a use-case diagram in UML with all high-level use cases possibly addressed by your module, to clarify the context and boundaries of your application.
Give each use case a concise, results-oriented name. Use cases should reflect the tasks the user needs to be able to accomplish using the system. Include an action verb and a noun.
Example:
Briefly describe each use case mentioning the following:
-
Actor. Name only the actor that will be initiating this use case, i.e. a person or other entity external to the software system being specified who interacts with the system and performs use cases to accomplish tasks.
-
Description. Provide a brief description of the reason for and outcome of this use case, or a high-level description of the sequence of actions and the outcome of executing the use case.
-
Preconditions and Postconditions. Include any activities that must take place, or any conditions that must be true, before the use case can be started (preconditions). Describe also the state of the system at the conclusion of the use case execution (postconditions).
-
Normal Flow. Provide a detailed description of the user actions and system responses that will take place during execution of the use case under normal, expected conditions. This dialog sequence will ultimately lead to accomplishing the goal stated in the use case name and description. This is best done as a numbered list of actions performed by the actor, alternating with responses provided by the system.
-
Alternative Flows and Exceptions. Document other, legitimate usage scenarios that can take place within this use case, stating any differences in the sequence of steps that take place. In addition, describe any anticipated error conditions that could occur during execution of the use case, and define how the system is to respond to those conditions.
Example:
| Name | Purchase tickets online |
| Actor | Customer |
| Description | The customer purchases one or more tickets for an event, using an electronic payment method, having the option to choose places. |
| Preconditions | - The customer has electronic payment means. - The event has tickets available on-sale. |
| Postconditions | - The customer gets the electronic tickets with a QR code. - The customer is charged of the tickets’ cost, and the seller credited. - Information of tickets sold & seats available for the event is updated. |
| Normal flow | 1. The customer accesses the web page of the ticketing system. 2. The system shows the list of events with tickets on-sale. 3. The customer selects the event and the number of tickets. 4. If wanted, the costumer may Choose Places. 5. The system shows the total price to pay. 6. The system redirects the customer to Electronic Payment. 7. The system delivers the electronic tickets to the customer with a unique identifier and QR code. |
| Alternative flows and exceptions | 1. [Payment failure] If, in step 6 of the normal flow the payment fails, the system gives the user the possibility to cancel or retry. |
The user stories should be created as GitHub issues. Therefore, this section will not exist in your report, it is here only to explain how you should describe the requirements of the product as user stories.
A user story is a description of desired functionality told from the perspective of the user or customer. A starting template for the description of a user story is
As a < user role >, I want < goal > so that < reason >.
User stories should be created and described as Issues in GitHub with the label "user story". See how to in the video Creating a Product Backlog of User Stories for Agile Development using GitHub.
You should name the issue with the text of the user story, and, in the "comments" field, add any relevant notes, the image(s) of the user interface mockup(s) (see below) and the acceptance test scenarios (see below).
INVEST in good user stories. You may add more details after, but the shorter and complete, the better. In order to decide if the user story is good, please follow the INVEST guidelines.
User interface mockups. After the user story text, you should add a draft of the corresponding user interfaces, a simple mockup or draft, if applicable.
Acceptance tests. For each user story you should write also the acceptance tests (textually in Gherkin), i.e., a description of scenarios (situations) that will help to confirm that the system satisfies the requirements addressed by the user story.
Value and effort. At the end, it is good to add a rough indication of the value of the user story to the customers (e.g. MoSCoW method) and the team should add an estimation of the effort to implement it, for example, using t-shirt sizes (XS, S, M, L, XL).
To better understand the context of the software system, it is very useful to have a simple UML class diagram with all the key concepts (names, attributes) and relationships involved of the problem domain addressed by your module. Also provide a short textual description of each class.
Example:
