HOTFIX: Añadidos de nuevo los ark42help

docs/src/02_architecture_constraints.adoc

@@ -1,26 +1,47 @@
+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 of the project to be graded adequately, it must use _GitHub_ as its version control software. The contributions of each team member and agreements reached must be easily traceable.
 |*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.
@@ -35,13 +56,10 @@
 [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.
 |===
-
-=======

docs/src/03_system_scope_and_context.adoc

@@ -4,21 +4,70 @@ ifndef::imagesdir[:imagesdir: ../images]
 == 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=3 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. 
-
 |===
 
 === 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.
+
+****
 
 The following diagram represents the general structure of the project, as well as the communication channels between various system components. It shows communication to external sources, as well as communications between the various microsystems.
 

docs/src/09_architecture_decisions.adoc

@@ -5,6 +5,33 @@ ifndef::imagesdir[:imagesdir: ../images]
 
 
 [role="arc42help"]
+****
+.Contents
+Important, expensive, large scale or risky architecture decisions including rationales.
+With "decisions" we mean selecting one alternative based on given criteria.
+
+Please use your judgement to decide whether an architectural decision should be documented
+here in this central section or whether you better document it locally
+(e.g. within the white box template of one building block).
+
+Avoid redundancy. 
+Refer to section 4, where you already captured the most important decisions of your architecture.
+
+.Motivation
+Stakeholders of your system should be able to comprehend and retrace your decisions.
+
+.Form
+Various options:
+
+* ADR (https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions[Documenting Architecture Decisions]) for every important decision
+* List or table, ordered by importance and consequences or:
+* more detailed in form of separate sections per decision
+
+.Further Information
+
+See https://docs.arc42.org/section-9/[Architecture Decisions] in the arc42 documentation.
+There you will find links and examples about ADR.
+
 ****
 
 [options="header",cols="1,3,3"]
@@ -24,5 +51,4 @@ ifndef::imagesdir[:imagesdir: ../images]
 |MongoDB
 |Being a non-relational database, it is easier to use. In addition, it is used by large telecommunications companies.
 |Non-relational databases are the ones with which we have the least experience.
-
-****
+|===

docs/src/10_quality_requirements.adoc

@@ -4,18 +4,77 @@ ifndef::imagesdir[:imagesdir: ../images]
 == 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.
+
 ****
 
 To describe the quality requirements that the game will have, we will use quality scenarios. Quality scenarios describe 
 the action to be performed by the user or the system (stimulus) in order to generate a response to the interaction.
 
+=== 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.
+
 ****
 
-=== Quality Tree
 image::QualityTree.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.
+****
+
 Quality scenarios, also known as use cases, are detailed descriptions of situations in which a user interacts with 
 a system and describe the expected outcomes along with the conditions of the environment in which the interaction 
 occurs.

docs/src/11_technical_risks.adoc

@@ -5,6 +5,23 @@ ifndef::imagesdir[:imagesdir: ../images]
 
 
 [role="arc42help"]
+****
+.Contents
+A list of identified technical risks or technical debts, ordered by priority
+
+.Motivation
+“Risk management is project management for grown-ups” (Tim Lister, Atlantic Systems Guild.) 
+
+This should be your motto for systematic detection and evaluation of risks and technical debts in the architecture, which will be needed by management stakeholders (e.g. project managers, product owners) as part of the overall risk analysis and measurement planning.
+
+.Form
+List of risks and/or technical debts, probably including suggested measures to minimize, mitigate or avoid risks or reduce technical debts.
+
+
+.Further Information
+
+See https://docs.arc42.org/section-11/[Risks and Technical Debt] in the arc42 documentation.
+
 ****
 
 [options="header"]
@@ -13,6 +30,4 @@ ifndef::imagesdir[:imagesdir: ../images]
 
 |Knowledge of REACT         |It is a framework that no team member has used before. Therefore, we have all had to learn how to use it. 
 |Internal group conflicts   |Lack of free time for team members makes group work difficult. 
-|===
-
-****
+|===

docs/src/12_glossary.adoc

@@ -4,6 +4,30 @@ ifndef::imagesdir[:imagesdir: ../images]
 == Glossary
 
 [role="arc42help"]
+****
+.Contents
+The most important domain and technical terms that your stakeholders use when discussing the system.
+
+You can also see the glossary as source for translations if you work in multi-language teams.
+
+.Motivation
+You should clearly define your terms, so that all stakeholders
+
+* have an identical understanding of these terms
+* do not use synonyms and homonyms
+
+
+.Form
+
+A table with columns <Term> and <Definition>.
+
+Potentially more columns in case you need translations.
+
+
+.Further Information
+
+See https://docs.arc42.org/section-12/[Glossary] in the arc42 documentation.
+
 ****
 
 [cols="e,2e" options="header"]
@@ -14,5 +38,3 @@ ifndef::imagesdir[:imagesdir: ../images]
 |REACT          |Open source JavaScript library developed by Facebook to build interactive and responsive user interfaces (UI). It is one of the most popular tools for modern web application development.
 |Usability      |Ease with which users can interact with a product, system or application to achieve their objectives effectively, efficiently and satisfactorily. 
 |===
-
-****