Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Doc part 10 & 11 to master #24

Merged
merged 6 commits into from
Feb 17, 2024
Merged

Doc part 10 & 11 to master #24

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
02d8fc0
documentation part 10 && changes parts 1 and 4
uo264915 Feb 7, 2024
4415764
Merge pull request #21 from Arquisoft/pablo
uo264915 Feb 7, 2024
60d1aaa
settings
uo264915 Feb 7, 2024
9ad8661
Documentation of the technical risks
baraganio Feb 15, 2024
7743474
Correct some words spelling
baraganio Feb 15, 2024
5f76574
Merge pull request #23 from Arquisoft/carlos
uo264915 Feb 17, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added docs/images/10_1_Quality_Tree.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
75 changes: 1 addition & 74 deletions docs/src/01_introduction_and_goals.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,21 +11,10 @@ WIQ is the project of the current course of the Software Architecture course, wh

It consists of an application in which users can register and enter to play the quiz game.

[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

.Requisitos de alto nivel
.High level Requirements
* The system will have at least one web frontend deployed and access will be through the Web.
* Users will be able to register in the system and consult the history of their participation in the system: number of games, number of correct/failed questions, times, etc.
* Questions will be automatically generated from Wikidata data.
Expand All @@ -34,52 +23,10 @@ These include
* The system will allow access to user information through an API.
* The system will allow access to the information of the questions generated through an API.

[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.

****

=== 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
****

[options="header",cols="1,2"]
|===
|Goals|Details
Expand All @@ -91,26 +38,6 @@ A table with quality goals and concrete scenarios, ordered by priorities

=== 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"]
|===
|Role/Name|Contact|Expectations
Expand Down
33 changes: 4 additions & 29 deletions docs/src/04_solution_strategy.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,9 @@ ifndef::imagesdir[:imagesdir: ../images]
[[section-solution-strategy]]
== Solution Strategy

.Technology decisions
=== Technology decisions

[options="header",cols="1,2"]
|===
|Technology|Description
| _Git_ | _Software version control system_
Expand All @@ -17,7 +18,7 @@ ifndef::imagesdir[:imagesdir: ../images]
| _CSS_ | _A graphic programming language oriented to define the repesentation of a document._
|===

.Decisions on how to achieve key quality goals
=== Decisions on how to achieve key quality goals

* Usability: the team will take care to design a clear and accessible interface for any user. This will be based on web usability standards.

Expand All @@ -27,7 +28,7 @@ ifndef::imagesdir[:imagesdir: ../images]

* Testability: this is an important quality objective to ensure that the software is reliable, robust and error-free. It is important to implement appropriate software development practices, such as separation of concerns and modular design.

.Relevant Organizational Decisions
=== Relevant Organizational Decisions

Regarding the organization within the team, we have taken the following decisions:

Expand All @@ -38,29 +39,3 @@ Regarding the organization within the team, we have taken the following decision
* We use a Kanban board within github to have well organized and in a very clear way the tasks that each team member has to perform/is performing.


[role="arc42help"]
****
.Contents
A short summary and explanation of the fundamental decisions and solution strategies, that shape system architecture. It includes

* technology decisions
* decisions about the top-level decomposition of the system, e.g. usage of an architectural pattern or design pattern
* decisions on how to achieve key quality goals
* relevant organizational decisions, e.g. selecting a development process or delegating certain tasks to third parties.

.Motivation
These decisions form the cornerstones for your architecture. They are the foundation for many other detailed decisions or implementation rules.

.Form
Keep the explanations of such key decisions short.

Motivate what was decided and why it was decided that way,
based upon problem statement, quality goals and key constraints.
Refer to details in the following sections.


.Further Information

See https://docs.arc42.org/section-4/[Solution Strategy] in the arc42 documentation.

****
73 changes: 10 additions & 63 deletions docs/src/10_quality_requirements.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,71 +3,18 @@ ifndef::imagesdir[:imagesdir: ../images]
[[section-quality-scenarios]]
== 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.

****

=== 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.


****
:imagesdir: ../images
image::10_1_Quality_Tree.png[Business Context Diagram]

=== 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.
****
[options="header",cols="1,3"]
|===
|Quality Requirements|Scenarios|Priority
| _Privacity_ | _We will respect the privacy of the users, the user's data will be protected at all times. We will ensure the highest possible security, storing the user's sensitive information securely and trying to prevent any kind of attack or risk._ | _High_
| _Usability_ | _We want to offer the user the possibility to see his personal statistics, as well as a service of access to information and data storage, in an intuitive and efficient system for customers (as fast as possible)._ | _High_
| _Maintainability_ | _The design and architecture will allow for flexibility in the face of unexpected events during development, this feature is important because we want to reduce costs in terms of time._ | _Medium_
| _Testeability_| _The application will be subjected to unit, acceptance and load testing to prove that it works correctly. If new functionality is added to the map, it must be thoroughly tested before deployment._ | _High_
|===
29 changes: 9 additions & 20 deletions docs/src/11_technical_risks.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,23 +3,12 @@ ifndef::imagesdir[:imagesdir: ../images]
[[section-technical-risks]]
== Risks and Technical Debts


[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.

****
=== Technical Risks
|===
| Risk | Explanation | Solution
| No knowladge of React | Non member of the team has worked with React before. | Read React's documentation and search for exercises and tutorials of how to use the technology.
| Github | Most of us have use it, however, some have not in a project of that magnitude. Also there are some new features for everyone. | Transfer the knowledge of essential operations in Github from those who now them to those who don't, as well as search information about how to use the new features for everyone.
| Lost of team members | Any member could leave the project due to personal reasons. Risk that gets importance if we take into account we only are four members. | Don't make any member categorically essential, so we can avoid any part of the project from being orphaned.
| External dependencies | As the app will be deployed on an external server, there could be a situation where we can not deployed it due to an external issue. | Have a second deployment server in order to replace the first if it is not available.
| Insufficient tests | The lack of tests could trigger the release of some features with a not expected behaviour. | Make exhaustive tests on all the features that will be released on the app.
|===