Merge pull request #54 from Arquisoft/chore/documentation-fixes

chore: fixing some tables, plantuml diagrams and writing a title for …

docs/index.adoc

@@ -6,7 +6,7 @@
 // configure EN settings for asciidoc
 include::src/config.adoc[]
 
-= image:arc42-logo.png[arc42] Template
+= image:arc42-logo.png[arc42] WIQ_en2b
 :revnumber: 8.2 EN
 :revdate: January 2023
 :revremark: (based upon AsciiDoc version)

docs/src/01_introduction_and_goals.adoc

@@ -26,22 +26,21 @@ See the complete functional requirements in the xref:#section-annex[Annex] of th
 |===
 |Goal|Description
 | Functional suitability | The system shall fulfill its intended purpose effectively and efficiently, allowing users to register, log in, play the quiz, and access their user statistics.
-| Security | The system must prioritize user data security. It must implement robust authentication mechanisms for user registration and login. The API access points for user information and generated questions must be secured with proper authorization. 
-| Reliability | The system should be reliable in generating questions from Wikidata, ensuring that questions are accurate and diverse. The system must handle user registrations, logins, and game data storage without errors.
-| Availability | The system must be available 99.99% of the time a user tries to access it.
-| Maintainability | The system must be designed and implemented in a way that facilitates easy maintenance and updates.
-| Performance efficiency | The system must deliver optimal performance, ensuring responsive interactions for users. The automatic generation of questions from Wikidata and the real-time gameplay must be efficient. The system must handle N concurrent users.
-| Usability | The system must provide a user-friendly interface, making it easy for users to register, log in, and play the game. The system learning time for a user should be less than 4 hours.
-| Compatibility | The system must be compatible with various web browsers and devices, ensuring a seamless experience for users regardless of their choice of platform. It has to be well-optimized for different screen sizes and functionalities.
-| Transferability | The system must allow for easy transfer of user data and game-related information through its APIs.
+| Reliability | The system should be reliable in generating questions from Wikidata, ensuring that questions are accurate and diverse. The system shall handle user registrations, logins, and game data storage without errors.
+| Availability | The system shall be available 99% of the time a user tries to access it.
+| Maintainability | The system shall be designed and implemented in a way that facilitates easy maintenance and updates.
+| Performance efficiency | The system shall deliver optimal performance, ensuring responsive interactions for users. The automatic generation of questions from Wikidata and the real-time gameplay shall be efficient. The system shall handle N concurrent users.
+| Security | The system shall prioritize user data security. It shall implement robust authentication mechanisms for user registration and login. The API access points for user information and generated questions shall be secured with proper authorization. 
+| Usability | The system shall provide a user-friendly interface, making it easy for users to register, log in, and play the game. The system learning time for a user should be less than 4 hours.
+| Compatibility | The system shall be compatible with various web browsers and devices, ensuring a seamless experience for users regardless of their choice of platform. It has to be well-optimized for different screen sizes and functionalities.
 |===
 
 === Stakeholders
-[options="header",cols="1,1,2"]
+[options="header",cols="1,2"]
 |===
-|Role/Name|Contact|Expectations
-| 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.
+|Role/Name|Expectations
+| RTVE  | To have a new experimental version of the Saber y Ganar quiz show.
+| HappySw | Develop a good application that fullfills the requirements expected by the client.
+| Registered user | To play with an entertaining and easy-to-use application. An application with which the user learn about different topics.
+| Wikidata | Being able to offer service allowing people to use the data through the API.
 |===

docs/src/03_system_scope_and_context.adoc

@@ -2,7 +2,6 @@ ifndef::imagesdir[:imagesdir: ../images]
 [[section-system-scope-and-context]]
 == System Scope and Context
 === Business Context
-**<Diagram or Table>**
 
 image::BusinessContext.png[align="center",title="Business Context",link="BusinessContext.png]
 

docs/src/04_solution_strategy.adoc

@@ -25,8 +25,9 @@ We also have a Whatsapp community for the team, and a Notion wiki.
 
 === Important quality-related decisions
 
+[options="header",cols="1,2"]
 |===
-|*Quality attribute pursued*|*Solution chosen*
+|Quality attribute pursued|Solution chosen
 |Privacy|All stored password will be hashed, both client-side and server-side, to avoid password disclosure. The client-side password is also intended to prevent password discoverage in case it is a repeated one.
 |Robustness|Currently, all validations will take place server-side to avoid not being properly taken care of due to JavaScript desactivation, such as when using the NoScript plug-in
 |Availability|Since Wikidata has a 1 minute limit related to the API, the backend will start querying it upon start and fill the database with questions to increase speed and thus improve user experience|

docs/src/05_building_block_view.adoc

@@ -15,7 +15,7 @@ This is the overall view of the application. The diagram is composed of 3 elemen
 
 _**Overview Diagram**_
 
-image::BusinessContext.png["Overall view of the business context"]
+image::BusinessContext.png[align="center", title="Overall view of the business context"]
 
 Motivation::
 This will be the general sketch of the elements interacting inside the application, including the external elements that will include the application.
@@ -42,7 +42,7 @@ Here is an specification of the inner structure of the WIQ Application.
 
 ==== White Box _WIQ Application_
 
-image::ContainerDiagram.png["Container for the WIQ System"]
+image::ContainerDiagram.png[align="center", title="Container for the WIQ System"]
 
 [role="arc42help"]
 ****

docs/src/09_architecture_decisions.adoc

@@ -6,9 +6,9 @@ ifndef::imagesdir[:imagesdir: ../images]
 
 During the application development process, decisions had to be made as issues emerged. The most interesting design decisions are reflected in this architectural records:
 
+[options="header",cols="1,4"]
 |===
-|*Decision* |*Explanation*
-
+|Decision|Explanation
 |React
 |Offers a powerful combination of performance, flexibility, and developer experience, making it a popular choice for building modern web applications. One of the members of the group has already worked with it in the past. It allows us to build a good user interface for the application.
 

docs/src/10_quality_requirements.adoc

@@ -5,7 +5,32 @@ ifndef::imagesdir[:imagesdir: ../images]
 === Quality Tree
 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[]
+[plantuml,"Quality Tree",png]
+----
+@startuml 
+title Quality attributes
+agent Quality
+agent Security
+agent Reliability
+agent Transferability
+agent Usability
+agent "Performance Efficiency"
+agent Maintainability
+agent Availability
+agent Compatibility
+agent "Functional Suitability"
+
+Quality --- Security
+Quality --- Reliability
+Quality --- Transferability
+Quality --- Usability
+Quality --- "Performance Efficiency"
+Quality --- Maintainability
+Quality --- Availability
+Quality --- Compatibility
+Quality --- "Functional Suitability"
+@enduml
+----
 
 === Quality Scenarios
 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.
@@ -15,11 +40,11 @@ To obtain a measurable system response to stimulus corresponding to the various
 |===
 |Quality attribute|Scenario|Priority
 | Functional suitability | Users shall be able to register, log in, play the quiz, and access historical data without encountering errors or glitches. | High, Medium
-| Security | User data shall be securely handled. Robust authentication mechanisms shall be in place for user registration and login. API access points for user information and generated questions shall be secured with proper authorization. | High, High 
 | Reliability | The system shall reliably generate accurate and diverse questions from Wikidata. User registrations, logins, and game data storage shall be handled without errors. | High, Medium
 | Availability | The system shall be available 99.99% of the time when a user attempts to access it. | High, High
 | Performance efficiency | The system shall deliver optimal performance, ensuring responsive interactions for users. It shall efficiently generate questions from Wikidata and handle real-time gameplay with up to N concurrent users. | High, High
 | Usability | The system shall provide a user-friendly interface, allowing users to register, log in, and play the game with a learning time of less than 4 hours. | High, Medium
+| Security | User data shall be securely handled. Robust authentication mechanisms shall be in place for user registration and login. API access points for user information and generated questions shall be secured with proper authorization. | Medium, High 
 | Compatibility | The system shall be compatible with various web browsers and devices, providing a seamless experience for users regardless of their choice of platform. It shall be well-optimized for different screen sizes and functionalities. | High, Medium
 | Transferability | The system shall allow for easy transfer of user data and game-related information through its APIs. | Medium, High
 | Testability | The unit tests shall have at least 75% coverage. | High, Medium

docs/src/11_technical_risks.adoc

@@ -2,11 +2,9 @@ ifndef::imagesdir[:imagesdir: ../images]
 
 [[section-technical-risks]]
 == Risks and Technical Debts
-
-
+[options="header",cols="1,2,2"]
 |===
-|*Risk* |*Explanation* | *Mitigation proposed*
-
+|Risk|Explanation|Mitigation proposed
 |Little knowledge of the technologies to be used
 |For most of the members of the team, is the first time working with technologies as React or Wikidata
 |Explore technologies documentation to familiarize ourselves with the technology, and seek examples of use.