Merge pull request #46 from Arquisoft/Documentation

Documentation
Arquisoft · Feb 19, 2024 · 1d4444c · 1d4444c
2 parents a6f8a50 + 6fc24bd
commit 1d4444c
Show file tree

Hide file tree

Showing 5 changed files with 26 additions and 112 deletions.
diff --git a/docs/src/03_system_scope_and_context.adoc b/docs/src/03_system_scope_and_context.adoc
@@ -1,38 +1,38 @@
 ifndef::imagesdir[:imagesdir: ../images]
 
 [[section-system-scope-and-context]]
-# System Scope and Context
+== System Scope and Context
 
 
 [role="arc42help"]
 ---
 
-## Contents
-### Scope and context
+=== Contents
+==== Scope and context
 
 This project aims to develop a quiz game.
 The main constraints are developing the game as a web app and using Wikidata to obtain the questions and answers.
 
 ---
 
-## Business Context
+=== Business Context
 
 [role="arc42help"]
 
-### Contents
+==== Contents
 
 * *Users:* They interact directly with the application through the user interface provided by the frontend using React, HTML, CSS, and JavaScript.
 * *Wikidata API:* The application communicates with the Wikidata service to obtain questions and answers related to different topics. Requests are made using the HTTP protocol, and response data is received in JSON format.
 
 ---
 
-### Motivation
+==== Motivation
 
 Regarding the information exchanged with the application, it will require having a registered account to play, and it will also exchange information with a MongoDB database and Wikidata itself to obtain the questions.
 
 ---
 
-### Form
+==== Form
 
 |===
 
@@ -44,37 +44,36 @@ Regarding the information exchanged with the application, it will require having
 
 ---
 
-### Context diagram
+==== Context diagram
+
 [plantuml, "context", png]
 ----
 component "App" as app
-
 :User: -> [app]: Answer question
 [app] -> User: Return result
-
 database DB
 [app] -> DB: Ask for question
 DB -> [app]: Return question
-
 component "WikiData" as wd
 [app] --> wd: Ask for keyword
 wd --> [app]: Return keyword
 ----
 
 ---
 
-## Technical Context
+=== Technical Context
 
 [role="arc42help"]
 
-### Contents
+==== Contents
 
 * *HTTP Channel:* The application uses the HTTP protocol to communicate with the Wikidata API service.
 * *MongoDB Data Channel:* Interactions with the MongoDB database allow for storing and retrieving questions and answers.
 
 ---
 
-### Deployment diagram
+==== Deployment diagram
+
 [plantuml, "deployment", png]
 ----
 node "Aplication Server" as app
@@ -83,7 +82,6 @@ artifact "MongoDB Server"
 }
 node Wikidata as w
 node Interface as i
-
 app - db
 app -- w
 app -- i

diff --git a/docs/src/04_solution_strategy.adoc b/docs/src/04_solution_strategy.adoc
@@ -1,15 +1,15 @@
 ifndef::imagesdir[:imagesdir: ../images]
 
 [[section-solution-strategy]]
-# Solution Strategy
+= Solution Strategy
 
 [role="arc42help"]
-## Contents
+== Contents
 This page contains a short summary and explanation of the fundamental decisions and solution strategies, that shape system architecture.
 
 ---
 
-### Technology Decisions
+=== Technology Decisions
 Below, all the technologies to be used in the development of the application are listed:
 
 * *JavaScript / React:* A JavaScript library designed to facilitate the development of web applications.
@@ -20,7 +20,7 @@ Below, all the technologies to be used in the development of the application are
 
 ---
 
-### Top-Level Decisions
+=== Top-Level Decisions
 In this section, a summarized list of all decisions regarding the architecture of the application is included.
 
 |===
@@ -36,7 +36,7 @@ In this section, a summarized list of all decisions regarding the architecture o
 
 ---
 
-### Quality Goals
+=== Quality Goals
 Next, several quality goals are established, along with the decisions made to achieve them.
 
 |===
@@ -58,7 +58,7 @@ Next, several quality goals are established, along with the decisions made to ac
 
 ---
 
-### Relevant Organizational
+=== Relevant Organizational
 Regarding the organization of the team, we have decided to use agile methodologies for better and faster group work. In this project, we will follow the best practices of the SCRUM framework.
 
 Practices to be followed:
@@ -72,7 +72,7 @@ Additionally, "Issues" and the GitHub-provided Kanban (ToDo - In Progress - Done
 
 ---
 
-### Motivation
+=== Motivation
 This section addresses the fundamental decisions for the project's architecture.
 
 |===

diff --git a/docs/src/05_building_block_view.adoc b/docs/src/05_building_block_view.adoc
@@ -9,14 +9,14 @@ ifndef::imagesdir[:imagesdir: ../images]
 [plantuml, "level1", png]
 
 ----
-
+@startuml
 Actor User
 Component WIQ
 Component Wikidata 
 User -right-> WIQ: interacts with
 WIQ -right-> Wikidata: receives data
 Wikidata -right..> WIQ
-
+@enduml
 ----
 
 ==== Motivation

diff --git a/docs/src/09_architecture_decisions.adoc b/docs/src/09_architecture_decisions.adoc
@@ -4,35 +4,7 @@ ifndef::imagesdir[:imagesdir: ../images]
 == Architecture Decisions
 
 
-[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,2"]
 |===
@@ -41,4 +13,4 @@ There you will find links and examples about ADR.
 | MongoDB | It is decided to use MongoDB based on the recommendation of the faculty, as it is one of the most popular NoSQL databases and because it fits perfectly with the application's needs.
 | NodeJS | It is decided to use NodeJS since it is the recommended option by the subject's faculty and one of the most widely used technologies in this area of web applications, thus having extensive documentation and examples available on the Internet.
 | React | It is decided to use React since it is the recommended option by the subject's faculty.
-|===
+|===
diff --git a/docs/src/10_quality_requirements.adoc b/docs/src/10_quality_requirements.adoc
@@ -7,71 +7,15 @@ ifndef::imagesdir[:imagesdir: ../images]
 [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)
+.Quality Tree
 
-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.
-
-image::10-Quiality_Tree.png["Quality Tree"]
+image::10-Quality_Tree.png["Quality Tree"]
 
 ****
 
 === 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.
-****
 
 * Usage Scenarios
 
@@ -89,4 +33,4 @@ Tabular or free form text.
 |===
 |Quality Goal|Scenario|Response
 | Maintainability | Introduce new functionality. | Reuse key components in order to easily add that new functionality.
-|===
+|===