Skip to content

Commit

Permalink
Merge pull request #94 from Arquisoft/documentation_abel
Browse files Browse the repository at this point in the history 
Modificaciones de la documentación correctas
  • Loading branch information
@uo288574
uo288574 authored Apr 6, 2024
2 parents 944a8ea + 371c971 commit b3e290d
Show file tree
Hide file tree
Showing 15 changed files with 90 additions and 609 deletions.
Binary file added docs/images/QualityTree.jpg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed docs/images/QualityTree.png
View file
Binary file not shown.
14 changes: 2 additions & 12 deletions docs/index.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,20 +29,10 @@ ifdef::backend-html5[]
endif::backend-html5[]


include::src/about-arc42.adoc[]
// include::src/about-arc42.adoc[]

// horizontal line
***

[role="arc42help"]
****
[NOTE]
====
This version of the template contains some help and explanations.
It is used for familiarization with arc42 and the understanding of the concepts.
For documentation of your own system you use better the _plain_ version.
====
****
// ***


// numbering from here on
Expand Down
103 changes: 14 additions & 89 deletions docs/src/01_introduction_and_goals.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,117 +3,42 @@ 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.
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 WIQ web application allows users to play a game similar to the one of Saber y Ganar quiz show. This game consists on answering a number of questions with different types and subjects obtaining a prize for each question well answered. Game´s questions are automatically generated from data available in Wikidata (https://www.wikidata.org/).

* The system will have at least a web front-end which will be available and accessible through the web.
* 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, etc ..
* Users will be able to register with the system and obtain the historical data from their participation: number of games, questions passed and failed, times, etc.
* Questions will be automatically generated from data available in Wikidata.
* Questions have to be answered before some specific time.
* Each question will have one right answer and several incorrect ones or distractors. Both the right answer and the distractors should be automatically generated.
* Each question will have one right answer and several incorrect ones or "decoy answers". Both the right answer and the decoy ones should be automatically generated.
* The system will give access to the information about the users through an API.
* The system will give access to information about the generated questions through an API.


=== 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
****
.Quality goals ordered by priority (from most to least important)
[options="header",cols="1,3"]
|===
|Quality Goal|Description
| _Learnability_ | _Any user must be able to use the app with ease. The interface must remind the user to the one in Saber y Ganar quiz show._
| _Satisfaction_ | _Users will not get repeated questions in at least a hundred questions._
| _Modularity_ | _The application will be divided in modules so that a change on one component has minimal impact on other components._
| _Testability_ | _The application should be able to go through different test and complete them successfully._
| _Time behaviour_ | _Users will not have to wait more than 500ms to get a new question._
| _Learnability_ | Any user must be able to use the app with ease. The interface must remind the user to the one in Saber y Ganar quiz show.
| _Satisfaction_ | Users will not get repeated questions in at least a hundred questions.
| _Modularity_ | The application will be divided in modules so that a change on one component has minimal impact on other components.
| _Testability_ | The application should be able to go through different test and complete them successfully.
| _Time behaviour_ | Users will not have to wait more than 500ms to get a new question.
|===


=== 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="2,2,5"]
|===
|Role/Name|Contact|Expectations
| _Professors_ | _ASW module professors_ | _Get a great project which can be evaluated and shown in their github._
| _Developers_ | _wiq_es6c team_ | _Carrying out a full real project using all the knowledge obtained in the degree._
| _Responsible company_ | _HappySw_ | _Development of an experimental version of the Saber y Ganar quiz show._
| _Client_ | _RTVE_ | _Getting a Web App to promote its famous Saber y Ganar quiz show by letting their viewers enjoy a similar experience._
| _Main beneficiaries_ | _Public users_ | _Having a great time playing an interesting and easy to use quiz game._
| _Side beneficiaries_ | _Wikidata_ | _Obtain free promotion of their application and its ease to use in multiple projects._
| _Professors_ | ASW module professors | Get a great project which can be evaluated and shown in their github.
| _Developers_ | wiq_es6c team | Carrying out a full real project using all the knowledge obtained in the degree.
| _Responsible company_ | HappySw | Development of an experimental version of the Saber y Ganar quiz show.
| _Client_ | RTVE | Getting a Web App to promote its famous Saber y Ganar quiz show by letting their viewers enjoy a similar experience.
| _Main beneficiaries_ | Public users | Having a great time playing an interesting and easy to use quiz game.
| _Side beneficiaries_ | Wikidata | Obtain free promotion of their application and its ease to use in multiple projects.
|===
60 changes: 19 additions & 41 deletions docs/src/02_architecture_constraints.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,64 +3,42 @@ ifndef::imagesdir[:imagesdir: ../images]
[[section-architecture-constraints]]
== Architecture Constraints

[role="arc42help"]
****
.Contents
Any requirement that constraints software architects in their freedom of design and implementation decisions or decision about the development process. These constraints sometimes go beyond individual systems and are valid for whole organizations and companies.
.Motivation
Architects should know exactly where they are free in their design decisions and where they must adhere to constraints.
Constraints must always be dealt with; they may be negotiable, though.
.Form
Simple tables of constraints with explanations.
If needed you can subdivide them into
technical constraints, organizational and political constraints and
conventions (e.g. programming or versioning guidelines, documentation or naming conventions)
.Further Information
See https://docs.arc42.org/section-2/[Architecture Constraints] in the arc42 documentation.
****

=== Technical constraints

[cols="2,4" options="header"]
|===
|Constraint |Explanation
|*OS/Browser Independence* |The project must be available to the maximum amount of users feasible. That includes support for mainstream OSs (_Windows_, _Linux_, _MacOS_) and browsers. (_Chrome_, _Safari_, _Firefox_, _Edge_)
|*Usage of _REACT_* |The _REACT JS_ framework will be used to develop the front-end of the project.
|*Docker* | The application will operate within a Docker environment.
|*Version Control* |In order for the project to be graded adequately, it must use _GitHub_ as its version control system. The contributions of each team member and agreements reached must be easily traceable.
|*Wikidata* | To generate questions, WikiData would be used as a knowledge base. Wikidata is a free and open knowledge base that can be read and edited by both humans and machines. Wikidata acts as central storage for the structured data of its sister Wikimedia projects, including Wikipedia, Wikivoyage, Wiktionary, Wikisource and others.
|*Continuous integration and delivery* |The development must progress through frequent integration of small changes into the main branch. New features must be automatically deployed with ease. (In our case, using _Docker_)
|_OS/Browser Independence_ |The project must be available to the maximum amount of users feasible. That includes support for mainstream OSs (_Windows_, _Linux_, _MacOS_) and browsers. (_Chrome_, _Safari_, _Firefox_, _Edge_)
|_Usage of REACT_ |The _REACT JS_ framework will be used to develop the front-end of the project.
|_Docker_ | The application will operate within a Docker environment.
|_Version Control_ |In order for the project to be graded adequately, it must use _GitHub_ as its version control system. The contributions of each team member and agreements reached must be easily traceable.
|_Wikidata_ | To generate questions, WikiData would be used as a knowledge base. Wikidata is a free and open knowledge base that can be read and edited by both humans and machines. Wikidata acts as central storage for the structured data of its sister Wikimedia projects, including Wikipedia, Wikivoyage, Wiktionary, Wikisource and others.
|_Continuous integration and delivery_ |The development must progress through frequent integration of small changes into the main branch. New features must be automatically deployed with ease. (In our case, using _Docker_)
|===

=== Organizational constraints

[cols="2,7" options="header"]
|===
|Constraint |Explanation
|*Time* |The team has to complete the project during the semester.
|*Team size* |The development teams must be composed of 5-7 members. In our case, the final team is composed of 6 members.
|*Budget* |No budget is provided for the development, so any costs that may arise have to be covered by the development team.
|*Deliverables* |Along the development process, the team must prepare deliverables set for certain dates, consisting of documentation and/or application prototypes.
|*Team meetings* |In order to plan the development of the project, as well as to assign tasks and make design decisions, the team will participate in several meetings. These meetings can be done in and out of the classroom, as needed. A record must be created for every meeting, summarizing the progress made.
|*Project testing* |The development team must test acceptable coverage of the project using different methods (_unit testing_, _integration testing_, _acceptance testing_... etc.)
|*Knowledge* |There are many aspects of the development of this project that are foreign to some of us (usage of _REACT_, deployments, microsystems architecture... etc.) so some research is required to keep up.
|_Time_ |The team has to complete the project during the semester.
|_Team size_ |The development teams must be composed of 5-7 members. In our case, the final team is composed of 6 members.
|_Budget_ |No budget is provided for the development, so any costs that may arise have to be covered by the development team.
|_Deliverables_ |Along the development process, the team must prepare deliverables set for certain dates, consisting of documentation and/or application prototypes.
|_Team meetings_ |In order to plan the development of the project, as well as to assign tasks and make design decisions, the team will participate in several meetings. These meetings can be done in and out of the classroom, as needed. A record must be created for every meeting, summarizing the progress made.
|_Project testing_ |The development team must test acceptable coverage of the project using different methods (_unit testing_, _integration testing_, _acceptance testing_... etc.)
|_Knowledge_ |There are many aspects of the development of this project that are foreign to some of us (usage of _REACT_, deployments, microsystems architecture... etc.) so some research is required to keep up.
|===

=== Conventions

[cols="2,4" options="header"]
|===
|Constraint |Explanation
|*Use of English* |The totality of the project must be written in English, as to facilitate its understanding internationally.
|*Programming Language conventions* | We ought to follow the conventions specific to the programming languages we're employing.
|*Documentation format* |The documentation must adhere to the Arc42 method, ensuring it is clear, simple, and effective.
|*Clean code* |In order to ease the understanding and maintenance of the project, all code written must be organized, descriptive and easy to read.
|*Accesibility* |The application should be user-friendly, allowing all individuals to navigate effortlessly, irrespective of any disabilities, ensuring inclusivity for all users.
|*Microservices* | The application will be divided into microservices to facilitate its development.
|_Use of English_ |The totality of the project must be written in English, as to facilitate its understanding internationally.
|_Programming Language conventions_ | We ought to follow the conventions specific to the programming languages we're employing.
|_Documentation format_ |The documentation must adhere to the Arc42 method, ensuring it is clear, simple, and effective.
|_Clean code_ |In order to ease the understanding and maintenance of the project, all code written must be organized, descriptive and easy to read.
|_Accesibility_ |The application should be user-friendly, allowing all individuals to navigate effortlessly, irrespective of any disabilities, ensuring inclusivity for all users.
|_Microservices_ | The application will be divided into microservices to facilitate its development.
|===
63 changes: 4 additions & 59 deletions docs/src/03_system_scope_and_context.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,72 +3,18 @@ ifndef::imagesdir[:imagesdir: ../images]
[[section-system-scope-and-context]]
== System Scope and Context

[role="arc42help"]
****
.Contents
System scope and context - as the name suggests - delimits your system (i.e. your scope) from all its communication partners
(neighboring systems and users, i.e. the context of your system). It thereby specifies the external interfaces.
If necessary, differentiate the business context (domain specific inputs and outputs) from the technical context (channels, protocols, hardware).
.Motivation
The domain interfaces and technical interfaces to communication partners are among your system's most critical aspects. Make sure that you completely understand them.
.Form
Various options:
* Context diagrams
* Lists of communication partners and their interfaces.
.Further Information
See https://docs.arc42.org/section-3/[Context and Scope] in the arc42 documentation.
****

=== Business Context

[role="arc42help"]
****
.Contents
Specification of *all* communication partners (users, IT-systems, ...) with explanations of domain specific inputs and outputs or interfaces.
Optionally you can add domain specific formats or communication protocols.
.Motivation
All stakeholders should understand which data are exchanged with the environment of the system.
.Form
All kinds of diagrams that show the system as a black box and specify the domain interfaces to communication partners.
Alternatively (or additionally) you can use a table.
The title of the table is the name of your system, the three columns contain the name of the communication partner, the inputs, and the outputs.
****

[cols="1,2,2" options="header"]
|===
|Entity |Input |Output
|*User* | App usage and experience. | The user will introduce and send its credentials every time it creates a new account or logs into an existing one.
|*WebApp* | User data and input, as well as external API calls received. | Handled API calls, sent to their respective microservice in order to be processed and answered.
|*Wikidata* |Calls to Wikidata's REST API asking for certain data, which will be used to construct the questions. | Said data. Its format may vary, according to the necessities of the questions generator.
|_User_ | App usage and experience. | The user will introduce and send its credentials every time it creates a new account or logs into an existing one.
|_WebApp_ | User data and input, as well as external API calls received. | Handled API calls or calls to their respective microservice in order to be processed and answered.
|_Wikidata_ |Calls to Wikidata's REST API asking for certain data, which will be used to construct the questions. | Said data. Its format may vary, according to the necessities of the questions generator.
|===

=== Technical Context

[role="arc42help"]
****
.Contents
Technical interfaces (channels and transmission media) linking your system to its environment. In addition a mapping of domain specific input/output to the channels, i.e. an explanation which I/O uses which channel.
.Motivation
Many stakeholders make architectural decision based on the technical interfaces between the system and its context. Especially infrastructure or hardware designers decide these technical interfaces.
.Form
E.g. UML deployment diagram describing channels to neighboring systems,
together with a mapping table showing the relationships between channels and input/output.
****

[plantuml,"Technical_Context Diagram",png]
----
!pragma layout smetana
Expand All @@ -84,6 +30,5 @@ database "\nMongoDB\n" as MongoDB #white
User -right- "Web App" : "HTTPS\t"
"Web App" -right- "REST API" : HTTPS (REST)
"REST API" -right-- "MongoDB" : "\tHTTPS"
"Web App" -down- "Wikidata" : " HTTPS (REST)"
"REST API" -down- "Wikidata" : " HTTPS (REST)"
----

Loading

0 comments on commit b3e290d

Please sign in to comment.