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.

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

chore: Added sections 9 and 11 to the documentation and terms in the glossary #34

Merged
merged 6 commits into from
Feb 14, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
36 changes: 12 additions & 24 deletions docs/src/09_architecture_decisions.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,32 +4,20 @@ 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.
During the application development process, decisions had to be made as issues emerged. The most interesting design decisions are reflected in this architectural records:

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).
|===
|*Decision* |*Explanation*

Avoid redundancy.
Refer to section 4, where you already captured the most important decisions of your architecture.
|React
|Offers a powerful combination of performance, flexibility, and developer experience, making it a popular choice for building modern web applications. One of the members of the group has already worked with it in the past. It allows us to build a good user interface for the application.

.Motivation
Stakeholders of your system should be able to comprehend and retrace your decisions.
|SpringBoot
|This choice is based on the extensive experience accumulated by our team in developing with Java, as well as the familiarity and comfort offered by the tools and practices associated with the Spring Boot ecosystem.

.Form
Various options:
|PostgreSQL
|We have chosen to use the PostgreSQL database instead of MongoDB due to the relational nature of PostgreSQL, which offers a robust and coherent structure for storing and relating data. We made this decision to ensure data integrity, perform complex queries, and maintain consistency in our storage operations.

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

****
|React Libraries
|To enhance the efficiency and effectiveness of our development process, we've taken proactive steps to incorporate specific libraries into our project. These carefully chosen libraries, meticulously outlined in detail within issue #16.
|===
28 changes: 13 additions & 15 deletions docs/src/11_technical_risks.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,22 +4,20 @@ ifndef::imagesdir[:imagesdir: ../images]
== Risks and Technical Debts


[role="arc42help"]
****
.Contents
A list of identified technical risks or technical debts, ordered by priority
|===
|*Risk* |*Explanation* | *Mitigation proposed*

.Motivation
“Risk management is project management for grown-ups” (Tim Lister, Atlantic Systems Guild.)
|Little knowledge of the technologies to be used
|For most of the members of the team, is the first time working with technologies as React or Wikidata
|Explore technologies documentation to familiarize ourselves with the technology, and seek examples of use.

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.
|Lack of time
|We may face time constraints in fulfilling all the requirements for each deliverable and meeting every deadline.
|Try to maintain a steady and sustainable development pace. Prioritize building functional components initially, then iterate and enhance from there.

.Form
List of risks and/or technical debts, probably including suggested measures to minimize, mitigate or avoid risks or reduce technical debts.
|Coordination and responsability problems
|It is probably the first time involvement in developing a project from scratch, including decisions on architecture, design, and implementation, introduces various challenges. Misunderstandings regarding tasks and version control management errors can result in individuals inadvertently disrupting the work of others. Additionally, the necessity to make numerous decisions and reach agreements increases the likelihood of errors, potentially consuming significant time and effort.
|To ensure effective collaboration and organization, adhere to the teachers' instructions concerning GitHub, including utilizing features such as issues and pull requests, and maintain a disciplined approach to your work. Furthermore, leverage the collective knowledge and suggestions of every team member, integrating them with your existing expertise.
|===


.Further Information

See https://docs.arc42.org/section-11/[Risks and Technical Debt] in the arc42 documentation.

****
In terms of technical debt, it's likely to be significant due to our lack of familiarity with the majority of the technologies involved for most of the team. Both Wikidata and React present considerable challenges, and we anticipate accumulating substantial technical debt in both areas. At present, our only strategy for mitigation is to search for potential solutions online.
37 changes: 7 additions & 30 deletions docs/src/12_glossary.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -3,40 +3,17 @@ ifndef::imagesdir[:imagesdir: ../images]
[[section-glossary]]
== 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"]
|===
|Term |Definition

|<Term-1>
|<definition-1>
|React
|An open-source JavaScript library for developing user interfaces. It can be used to develop web applications, and it has to be complemented with other libraries to develop full-fledged products.

|SpringBoot
|Java Spring Boot (Spring Boot) is a tool that makes developing web application and microservices with Spring Framework faster and easier through three core capabilities: Autoconfiguration, an opinionated approach to configuration, the ability to create standalone applications.

|<Term-2>
|<definition-2>
|PostgreSQL
|Object-relational database management system (ORDMBS), which means that it has relational capabilities and an object-oriented design
|===