1st draft of documentation pages

docs/README.md

@@ -1,6 +1,6 @@
 ## The documentation
 In this project, the documentation is compiled locally and deployed to GitHub pages.
-The deployment url is: [https://arquisoft.github.io/wiq_0/](https://arquisoft.github.io/wiq_0/).
+The deployment url is: [https://arquisoft.github.io/wiq_7/](https://arquisoft.github.io/wiq_7/).
 
 ### Documentation build
 For the documentation, we are going to use [AsciiDoc](https://asciidoc.org/) and [PlantUML](https://plantuml.com) and follow the [Arc42](https://github.com/arc42/arc42-template) template. If you want to be able to generate the doc locally you need to install Ruby, Java and some dependencies to translate the AsciiDoc code into html. If you are in Linux you can install Ruby and Java simply by executing:
@@ -17,6 +17,8 @@ Once Ruby is working you can install some gems with `asciidoctor` and `asciidoct
 gem install asciidoctor asciidoctor-diagram
 ```
 
+If you include diagrams created with PlantUML, it is necessary to install [Graphviz](https://graphviz.org) to ensure they are generated correctly.
+
 Now it is turn to install some dependencies in the `package.json` file inside the `docs` directory:
 
 ```shell
@@ -30,6 +32,6 @@ npm run build
 The documentation will be generated under the `docs/build` directory. 
 
 ### Documentation deployment
-If we want to deploy it to GitHub pages, so it is accessible via [https://arquisoft.github.io/wiq_0/](https://arquisoft.github.io/wiq_0/), we need to execute `npm run deploy`.
+If we want to deploy it to GitHub pages, so it is accessible via [https://arquisoft.github.io/wiq_7/](https://arquisoft.github.io/wiq_7/), we need to execute `npm run deploy`.
 
 If you check the `package.json` in this directory you can see how deploying is as easy as executing `gh-pages -d build`, which can be directly executed using `npm run deploy` in the docs directory. The `gh-pages` package is in charge of pushing the documentation generated directory (basically some htmls) to a special github branch called gh-pages. Everything pushed to this branch is accessible on the repository page. Note that we only want to push there the documentation. Also is important that the documentation build is not pushed to the other branches of the project.

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 7 Documentation
 :revnumber: 8.2 EN
 :revdate: January 2023
 :revremark: (based upon AsciiDoc version)

docs/package.json

@@ -4,12 +4,11 @@
     "description": "Npm project just for the docs",
     "main": "index.js",
     "scripts": {
-      "build": "shx rm -rf build && asciidoctor -D build -a imagesdir=./images -r asciidoctor-diagram index.adoc && shx cp -R images build",
-      "deploy": "gh-pages -d build"
+        "build": "shx rm -rf build && asciidoctor -D build -a imagesdir=./images -r asciidoctor-diagram index.adoc && shx cp -R images build",
+        "deploy": "gh-pages -d build"
     },
     "dependencies": {
-      "gh-pages": "^3.2.3",
-      "shx": "^0.3.3"
+        "gh-pages": "^6.1.1",
+        "shx": "^0.3.3"
     }
-  }
-
+}

docs/src/01_introduction_and_goals.adoc

@@ -1,93 +1,64 @@
-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
-****
-
-=== 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.
+== Introduction and Goals
 
-Keep these excerpts as short as possible. Balance readability of this document with potential redundancy w.r.t to requirements documents.
+Saber y Ganar is the Software Architecture project developed by Ángel Luis Álvarez Iglesias (uo17919), under the supervision of Jorge Álvarez Fidalgo.
 
+This project consists of an application that features a question-and-answer game, designed to be both engaging and educational. Additionally, the application offers a statistics tracking system, allowing registered users to view their own performance metrics and compare them with those of other players.
 
-.Further Information
+The application is built using the MERN stack, which includes MongoDB for the database, Express.js for the server-side framework, React for the front-end development, and Node.js for the runtime environment.
 
-See https://docs.arc42.org/section-1/[Introduction and Goals] in the arc42 documentation.
+=== Requirements Overview
 
-****
+[cols="1,3", options="header"]
+|===
+| Requirement Code | Description
+| RE1
+| The system will have at least a web front-end which will be available and accessible through the web.
+| RE2
+| Users will be able to register to the system and obtain the historical data from their participation: number of games, questions passed and failed, times, ...
+| RE3
+| Questions will be automatically generated from data available in Wikidata.
+| RE4
+| Questions have to be answered before some specific time.
+| RE5
+| Each question will have one right answer and several incorrect ones or distractors. Both the right answer and the distractors should be automatically generated.
+| RE6
+| The system will give access to the information about the users through an API.
+| RE7
+| The system will give access to information about the generated questions through an API.
+| RE8
+| Allow different game modes like the ones that appear in the quiz show page (Each wise man with his subject, Travel with us, The hot question, Discovering cities, ...).
+|===
 
 === 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
-****
+[cols="1,2,1", options="header"]
+|===
+| Quality Objective | Implementation | Priority
+| Usability 
+| To ensure the application is user-friendly, we will maintain a consistent design and emphasize predictability, making it easy to learn and providing a seamless user experience.| 5
+| Testability 
+| We will perform thorough tests to ensure the proper functioning of all services within the application. | 4
+| Performance 
+| We will strive to optimize resource usage within the application to ensure its performance remains fast and efficient. | 4
+| Reliability 
+| We will focus on building a robust application by implementing error-handling mechanisms and redundancy measures to ensure consistent performance and minimize downtime. | 3
+| Security 
+| The goal is to meet essential security standards to prevent unauthorized access to accounts and protect user information from exposure. However, this is not a primary objective of the project. | 1
+|===
 
 === 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"]
+[cols="1,2,2", options="header"]
 |===
-|Role/Name|Contact|Expectations
-| _<Role-1>_ | _<Contact-1>_ | _<Expectation-1>_
-| _<Role-2>_ | _<Contact-2>_ | _<Expectation-2>_
+| Role | Description | Expectations
+| Client 
+| Our client is RTVE, represented by the course instructors, who have requested the development of an application based on the "Saber y Ganar" TV show. | An application that fulfills all the requirements outlined in the section above.
+| Development team 
+| The student uo17919. | Develop a comprehensive application as described in the lab practice guide. It must meet all specified requirements and clearly demonstrate the effort invested in the project.
+| Users 
+| The target audience for the application (the players) who will test or use the final product. | A fun and well-functioning game that features a variety of questions to offer a challenging experience.
+| Github users 
+| The users who will access the project repository on Github. | A well-documented project that is easy to understand and navigate, featuring high-quality code and a clear architecture.
 |===