Skip to content

Commit

Permalink
chore: finishing documentation.
Browse files Browse the repository at this point in the history
  • Loading branch information
@UO282104
UO282104 committed Feb 15, 2024
1 parent 741a3b7 commit 0f9af18
Show file tree
Hide file tree
Showing 4 changed files with 91 additions and 229 deletions.
4 changes: 3 additions & 1 deletion docs/index.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -96,4 +96,6 @@ include::src/11_technical_risks.adoc[]
// 12. Glossary
include::src/12_glossary.adoc[]


<<<<
// 13. Annex
include::src/13_annex.adoc[]
171 changes: 6 additions & 165 deletions docs/src/01_introduction_and_goals.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,45 +2,9 @@ ifndef::imagesdir[:imagesdir: ../images]

[[section-introduction-and-goals]]
== Introduction and Goals

[role="arc42help"]
****
Describes the relevant requirements and the driving forces that software architects and development team must consider.
These include
* underlying business goals,
* essential features,
* essential functional requirements,
* quality goals for the architecture and
* relevant stakeholders and their expectations
****
RTVE has hired the company HappySw, composed of students from the Oviedo School of Software Engineering, to develop a new experimental version of the quiz show Saber y Ganar. This application will be called WIQ, where users will be able to register and log in to play. The application will consist of answering questions of different types generated with Wikidata. For each question answered correctly, points will be obtained.

=== Requirements Overview

[role="arc42help"]
****
.Contents
Short description of the functional requirements, driving forces, extract (or abstract)
of requirements. Link to (hopefully existing) requirements documents
(with version number and information where to find it).
.Motivation
From the point of view of the end users a system is created or modified to
improve support of a business activity and/or improve the quality.
.Form
Short textual description, probably in tabular use-case format.
If requirements documents exist this overview should refer to these documents.
Keep these excerpts as short as possible. Balance readability of this document with potential redundancy w.r.t to requirements documents.
.Further Information
See https://docs.arc42.org/section-1/[Introduction and Goals] in the arc42 documentation.
****

* The system will provide non-registered users with the option to sign up.
* The system will provide unidentified users with the option to log in.
* The system can only be used by registered users.
Expand All @@ -54,105 +18,10 @@ See https://docs.arc42.org/section-1/[Introduction and Goals] in the arc42 docum
* The system will offer registered users access the ranking of the game.
* The system will set a time limit for registered users to respond to each question.

==== Functional Requirements
===== Users Sign up.
[none or no-bullet]
* FR-USU 1. The system will offer to an unregistered user a registration form.
* FR-USU 2. The system will request the necessary data to register the new user.
[none or no-bullet]
** FR-USU 2.1. The system will request the following data to register the new user:
[none or no-bullet]
*** FR-USU 2.1.1. Username.
*** FR-USU 2.1.2. Email address.
*** FR-USU 2.1.3. Password.
*** FR-USU 2.1.4. All data fields are mandatory.
* FR-USU 3. When any value entered by the new user is invalid, the user will receive a message notifying the error and will not be able to register.
* FR-USU 4. When all the values entered by the new user are valid, the system will check if the user is already registered in the persistence system.
[none or no-bullet]
** FR-USU 4.1. When a user with the same data is already found in the persistence system, the user will not be able to create a new account since it already exists.
** FR-USU 4.2. When no user matching the data is found in the persistence system.
[none or no-bullet]
*** FR-USU 4.2.1. The new user will be registered in the system.

===== Users Log in.
[none or no-bullet]
* FR-ULI 1. The system must allow an unidentified user to log in.
[none or no-bullet]
** FR-ULI 1.1. The system will request the email address as the user identifier.
[none or no-bullet]
*** FR-ULI 1.1.1. The system must check that its format is valid.
*** FR-ULI 1.1.2. It is a mandatory field.
** FR-ULI 1.2. The system will request the user's password.
[none or no-bullet]
*** FR-ULI 1.2.1. It is a mandatory field.
** FR-ULI 1.3. The system will automatically validate the entered data to verify when it corresponds to a registered user account.
[none or no-bullet]
*** FR-ULI 1.3.1. When the user is not stored in the persistence system, an error message will be displayed.
*** FR-ULI 1.3.2. When the user exists in the persistence system, but the passwords do not match, a message will be displayed to the user notifying them of the error.
*** FR-ULI 1.3.3. When the user is stored in the persistence system and the passwords match, the user will be logged in.
* FR-ULI 2. The system must allow users who are logged in to log out.

===== Data management by the user.
[none or no-bullet]
* FR-DMU 1. The system will allow all registered users to access their historical data from their participation.
[none or no-bullet]
** FR-DMU 1.1. Registered users will be able to access the number of games they have played.
** FR-DMU 1.2. Registered users will be able to access the number of questions they have answered correctly.
** FR-DMU 1.3. Registered users will be able to access the number of questions they have answered incorrectly.
** FR-DMU 1.4. Registered users will be able to access the time they have spent within the system.
** FR-DMU 1.5. Registered users will be able to access the ranking of the game.
See the complete functional requirements in the xref:#section-annex[Annex] of the documentation.

===== Play to WIQ.
[none or no-bullet]
* FR-PWIQ 1. The system will only allow registered users to play the WIQ game.
* FR-PWIQ 2. The game consists of nine rounds.
[none or no-bullet]
** FR-PWIQ 2.1. In each round, the system will automatically generate a question to the registered user.
** FR-PWIQ 2.2. In each round, the system will provide the registered user with four automatically generated possible answers.
** FR-PWIQ 2.3. In each round, there will always be only one correct answer.
** FR-PWIQ 2.4. The system will automatically end the game after completing the ninth round.
* FR-PWIQ 3. The registered user must respond to the question before the specified time expires.
[none or no-bullet]
** FR-PWIQ 3.1. When the specified time has not ended, and the registered user has provided an answer:
[none or no-bullet]
*** FR-PWIQ 3.1.1. The system will check if the answer is correct.
[none or no-bullet]
**** FR-PWIQ 3.1.1.1. When the answer is correct:
[none or no-bullet]
***** FR-PWIQ 3.1.1.1.1. The registered user will earn 10 points.
***** FR-PWIQ 3.1.1.1.2. When the registered user is in the ninth round, the system will end the game.
***** FR-PWIQ 3.1.1.1.3. When the registered user is not in the ninth round, the system will move to the next round.
**** FR-PWIQ 3.1.1.2. When the answer is incorrect:
[none or no-bullet]
***** FR-PWIQ 3.1.1.2.1. When the registered user is in the ninth round, the system will end the game.
***** FR-PWIQ 3.1.1.2.2. When the registered user is not in the ninth round, the system will move to the next round.
** FR-PWIQ 3.2. When the specified time has ended:
[none or no-bullet]
*** FR-PWIQ 3.2.1. When the registered user is in the ninth round, the system will end the game.
*** FR-PWIQ 3.2.2. When the registered user is not in the ninth round, the system will move to the next round.

=== Quality Goals

[role="arc42help"]
****
.Contents
The top three (max five) quality goals for the architecture whose fulfillment is of highest importance to the major stakeholders.
We really mean quality goals for the architecture. Don't confuse them with project goals.
They are not necessarily identical.
Consider this overview of potential topics (based upon the ISO 25010 standard):
image::01_2_iso-25010-topics-EN.drawio.png["Categories of Quality Requirements"]
.Motivation
You should know the quality goals of your most important stakeholders, since they will influence fundamental architectural decisions.
Make sure to be very concrete about these qualities, avoid buzzwords.
If you as an architect do not know how the quality of your work will be judged...
.Form
A table with quality goals and concrete scenarios, ordered by priorities
****

[options="header",cols="1,3"]
|===
|Goal|Description
Expand All @@ -168,39 +37,11 @@ A table with quality goals and concrete scenarios, ordered by priorities
|===

=== Stakeholders

[role="arc42help"]
****
.Contents
Explicit overview of stakeholders of the system, i.e. all person, roles or organizations that
* should know the architecture
* have to be convinced of the architecture
* have to work with the architecture or with code
* need the documentation of the architecture for their work
* have to come up with decisions about the system or its development
.Motivation
You should know all parties involved in development of the system or affected by the system.
Otherwise, you may get nasty surprises later in the development process.
These stakeholders determine the extent and the level of detail of your work and its results.
.Form
Table with role names, person names, and their expectations with respect to the architecture and its documentation.
****

[options="header",cols="1,2,2"]
[options="header",cols="1,1,2"]
|===
|Role/Name|Contact|Expectations
| RTVE | Client | _<Expectation-1>_
| HappySw | Software Development Team | _<Expectation-2>_
| Registered user | _<Contact-3>_ | _<Expectation-2>_
| Usability expert | _<Contact-3>_ | _<Expectation-2>_
| Accesibility expert | _<Contact-3>_ | _<Expectation-2>_
| Security expert | _<Contact-3>_ | _<Expectation-2>_
| Design expert | _<Contact-3>_ | _<Expectation-2>_
| DNS provider | _<Contact-3>_ | _<Expectation-2>_
| Translation team | _<Contact-3>_ | _<Expectation-2>_
| Project Manager | _<Contact-3>_ | _<Expectation-2>_
| Wikidata | _<Contact-3>_ | _<Expectation-2>_
| RTVE | [email protected] | To have a new experimental version of the Saber y Ganar quiz show.
| HappySw | [email protected] | Develop a good application that fullfills the requirements expected by the client.
| Registered user | Unknown | To play with an entertaining and easy-to-use application. An application with which the user learn about different topics.
| Wikidata | [email protected] | Being able to offer service allowing people to use the data through the API.
|===
65 changes: 2 additions & 63 deletions docs/src/10_quality_requirements.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,74 +2,13 @@ ifndef::imagesdir[:imagesdir: ../images]

[[section-quality-scenarios]]
== Quality Requirements


[role="arc42help"]
****
.Content
This section contains all quality requirements as quality tree with scenarios. The most important ones have already been described in section 1.2. (quality goals)
Here you can also capture quality requirements with lesser priority,
which will not create high risks when they are not fully achieved.
.Motivation
Since quality requirements will have a lot of influence on architectural
decisions you should know for every stakeholder what is really important to them,
concrete and measurable.
.Further Information
See https://docs.arc42.org/section-10/[Quality Requirements] in the arc42 documentation.
****

=== Quality Tree

[role="arc42help"]
****
.Content
The quality tree (as defined in ATAM – Architecture Tradeoff Analysis Method) with quality/evaluation scenarios as leafs.
.Motivation
The tree structure with priorities provides an overview for a sometimes large number of quality requirements.
.Form
The quality tree is a high-level overview of the quality goals and requirements:
* tree-like refinement of the term "quality". Use "quality" or "usefulness" as a root
* a mind map with quality categories as main branches
In any case the tree should include links to the scenarios of the following section.
****
This quality tree is a high-level overview of the quality goals and requirements. The Quality tree uses "quality" as a root while the rest of the quality categories will be displayed as branches.

image:10_Quality_Tree.png[]

=== Quality Scenarios

[role="arc42help"]
****
.Contents
Concretization of (sometimes vague or implicit) quality requirements using (quality) scenarios.
These scenarios describe what should happen when a stimulus arrives at the system.
For architects, two kinds of scenarios are important:
* Usage scenarios (also called application scenarios or use case scenarios) describe the system’s runtime reaction to a certain stimulus. This also includes scenarios that describe the system’s efficiency or performance. Example: The system reacts to a user’s request within one second.
* Change scenarios describe a modification of the system or of its immediate environment. Example: Additional functionality is implemented or requirements for a quality attribute change.
.Motivation
Scenarios make quality requirements concrete and allow to
more easily measure or decide whether they are fulfilled.
Especially when you want to assess your architecture using methods like ATAM you need to describe your quality goals (from section 1.2)
more precisely down to a level of scenarios that can be discussed and evaluated.
.Form
Tabular or free form text.
****
To obtain a measurable system response to stimulus corresponding to the various quality branches outlined in the mindmap, we will use quality scenarios. Scenarios make quality requirements concrete and allow to more easily measure or decide whether they are fulfilled.

==== Usage Scenarios
[options="header",cols="1,3,1"]
Expand Down
80 changes: 80 additions & 0 deletions docs/src/13_annex.adoc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
ifndef::imagesdir[:imagesdir: ../images]

[[section-annex]]
== Annex
=== Functional Requirements
==== Users Sign up.
[none or no-bullet]
* FR-USU 1. The system will offer to an unregistered user a registration form.
* FR-USU 2. The system will request the necessary data to register the new user.
[none or no-bullet]
** FR-USU 2.1. The system will request the following data to register the new user:
[none or no-bullet]
*** FR-USU 2.1.1. Username.
*** FR-USU 2.1.2. Email address.
*** FR-USU 2.1.3. Password.
*** FR-USU 2.1.4. All data fields are mandatory.
* FR-USU 3. When any value entered by the new user is invalid, the user will receive a message notifying the error and will not be able to register.
* FR-USU 4. When all the values entered by the new user are valid, the system will check if the user is already registered in the persistence system.
[none or no-bullet]
** FR-USU 4.1. When a user with the same data is already found in the persistence system, the user will not be able to create a new account since it already exists.
** FR-USU 4.2. When no user matching the data is found in the persistence system.
[none or no-bullet]
*** FR-USU 4.2.1. The new user will be registered in the system.

==== Users Log in.
[none or no-bullet]
* FR-ULI 1. The system must allow an unidentified user to log in.
[none or no-bullet]
** FR-ULI 1.1. The system will request the email address as the user identifier.
[none or no-bullet]
*** FR-ULI 1.1.1. The system must check that its format is valid.
*** FR-ULI 1.1.2. It is a mandatory field.
** FR-ULI 1.2. The system will request the user's password.
[none or no-bullet]
*** FR-ULI 1.2.1. It is a mandatory field.
** FR-ULI 1.3. The system will automatically validate the entered data to verify when it corresponds to a registered user account.
[none or no-bullet]
*** FR-ULI 1.3.1. When the user is not stored in the persistence system, an error message will be displayed.
*** FR-ULI 1.3.2. When the user exists in the persistence system, but the passwords do not match, a message will be displayed to the user notifying them of the error.
*** FR-ULI 1.3.3. When the user is stored in the persistence system and the passwords match, the user will be logged in.
* FR-ULI 2. The system must allow users who are logged in to log out.

==== Data management by the user.
[none or no-bullet]
* FR-DMU 1. The system will allow all registered users to access their historical data from their participation.
[none or no-bullet]
** FR-DMU 1.1. Registered users will be able to access the number of games they have played.
** FR-DMU 1.2. Registered users will be able to access the number of questions they have answered correctly.
** FR-DMU 1.3. Registered users will be able to access the number of questions they have answered incorrectly.
** FR-DMU 1.4. Registered users will be able to access the time they have spent within the system.
** FR-DMU 1.5. Registered users will be able to access the ranking of the game.

==== Play to WIQ.
[none or no-bullet]
* FR-PWIQ 1. The system will only allow registered users to play the WIQ game.
* FR-PWIQ 2. The game consists of nine rounds.
[none or no-bullet]
** FR-PWIQ 2.1. In each round, the system will automatically generate a question to the registered user.
** FR-PWIQ 2.2. In each round, the system will provide the registered user with four automatically generated possible answers.
** FR-PWIQ 2.3. In each round, there will always be only one correct answer.
** FR-PWIQ 2.4. The system will automatically end the game after completing the ninth round.
* FR-PWIQ 3. The registered user must respond to the question before the specified time expires.
[none or no-bullet]
** FR-PWIQ 3.1. When the specified time has not ended, and the registered user has provided an answer:
[none or no-bullet]
*** FR-PWIQ 3.1.1. The system will check if the answer is correct.
[none or no-bullet]
**** FR-PWIQ 3.1.1.1. When the answer is correct:
[none or no-bullet]
***** FR-PWIQ 3.1.1.1.1. The registered user will earn 10 points.
***** FR-PWIQ 3.1.1.1.2. When the registered user is in the ninth round, the system will end the game.
***** FR-PWIQ 3.1.1.1.3. When the registered user is not in the ninth round, the system will move to the next round.
**** FR-PWIQ 3.1.1.2. When the answer is incorrect:
[none or no-bullet]
***** FR-PWIQ 3.1.1.2.1. When the registered user is in the ninth round, the system will end the game.
***** FR-PWIQ 3.1.1.2.2. When the registered user is not in the ninth round, the system will move to the next round.
** FR-PWIQ 3.2. When the specified time has ended:
[none or no-bullet]
*** FR-PWIQ 3.2.1. When the registered user is in the ninth round, the system will end the game.
*** FR-PWIQ 3.2.2. When the registered user is not in the ninth round, the system will move to the next round.

0 comments on commit 0f9af18

Please sign in to comment.