Merge pull request #17 from dancier/feature/rework-some-things

improved parts of the Arc42 documentation (beginning up to & includin…

src/main/jbake/content/documentation/arc42/src/01_introduction_and_goals.adoc

@@ -1,19 +1,19 @@
 [[section-introduction-and-goals]]
 == Introduction and Goals
 
-Partner dance is great from many perspectives:
+Participating in partner dances offers numerous benefits:
 
 * It brings people together _(social perspective)_
 * Dancing is a good full-body workout _(physical health perspective)_
 * Dancing relieves stress _(mental health perspective)_
 * In general, people who dance seem to be less interested in starting wars _(society's perspective)_
 * Last but not least, you can find a partner for life _(mankind's survival perspective)_
 
-*BUT!*
+*HOWEVER*
 
-There is often one barrier for someone starting with a partner dance. You have to find a partner to dance with.
+There is often one barrier for individuals wanting to beging with partner dances — they need to find a dance partner.
 
-Dancier is there to help all those people!
+Dancier is here to help all those people!
 
 
 === Functional Requirements
@@ -43,8 +43,8 @@ Based on that, we provide details on what is required for our https://en.wikiped
 | Matched dancers (M2) should have the capability to communicate with their matches, to arrange a dance.
 
 | O1
-| Schools/Event-Organisers can provide information 
-| Dancier should match dance courses, and dance events in general to its main users. 
+| Schools/Event-Organisers can provide information
+| Dancier should match dance courses, and dance events in general to its main users.
 
 | O2
 | Match dance classes with dancers

src/main/jbake/content/documentation/arc42/src/02_constraints.adoc

@@ -2,31 +2,31 @@
 
 == Architecture/Technical Constraints
 
-The only constraint we have is, to obey our architectural principles. Find them https://project.dancier.net/architecture-decision-principles.html[here].
+The only constraints we have is to obey our architectural principles. Find them https://project.dancier.net/architecture-decision-principles.html[here].
 
 === Organizational Constraints
 [options="header", cols="1,1,1"]
 |===
 |Id|Constraint|Description
 |OC1
 |Founder is Marc
-|Is a dancer, who wants a platform to connect Dancers. Wants to learn how to drive a product holistically. Have a reference project. May earn something, somewhen with it.
+|Is a dancer, who wants a platform to connect Dancers. Wants to learn how to drive a product holistically. Have a reference project. May find potential for future earnings.
 
 |OC2
 |Team's Motivation
 |Wants to learn how to drive a product holistically. Have a great time working together. Have a reference project. No intention to earn anything with it.
 
 |OC3
 |Work-mode: startup
-|Only do things that immediately pay off in the next 6 months. For everything that slows us down and pays off later: do not do this.
+|Only do things that immediately pay off within the next 6 months. For everything that slows us down and pays off later: do not do this.
 
-|OC4|Licence|All the source code will be released under an open-source license. Everyone can fork the project and start a dancier on his own (with another name of course)
+|OC4|Licence|All  source code will be released under an open-source license. Everyone can fork the project and start a dancier on their own (with a different name, of course)
 |===
 
 === Conventional Constraints
 [options="header", cols="1,1,1"]
 |===
 |Id|Convention|Description
-|C1|Be polite|being aggressive, rude... will never do anything good
-|C2|Hear first, judge less|Confronted with some point of view that seems strange to you: give your college the chance to explain.
-|===
+|C1|Be polite|being aggressive or rude... will never do anything good.
+|C2|Listen first, judge less|When confronted with a different point of view, give your colleague the chance to explain themselves.
+|===

src/main/jbake/content/documentation/arc42/src/03_system_scope_and_context.adoc

@@ -12,13 +12,13 @@ image:functional-context.drawio.svg[]
 |Neighbor| Description
 
 | Dancer
-| Dancing people looking out for other dancers and dance-related information. We plan that the system should be able to cope with at least 10.000 dancing people.
+| Individuals who engage in dancing, seeking fellow dancers and dance-related information. The system is designed to accommodate at least 10,000 dancers.
 
 | School
-| Schools that offer dance courses, dance workshops and other dance-related stuff. They use Dancier as a channel to connect to dancers.
+| Institutions providing dance courses, workshops, and other dance-related activities. They utilize Dancier as a platform to connect with dancers and promote their activities.
 
 | Event Organisers
-| Organisors of all dance-related events use Dancier to connect to potential participants.
+| Organizers of various dance-related events use Dancier as a means to connect with potential participants.
 
 |===
 
@@ -29,6 +29,6 @@ image:technical-context.drawio.svg[]
 [options="header", cols="1,5"]
 |===
 | Neighbor | Description
-| SMTP-Server | Used to send emails to its stakeholders
-| Web-Client | Each Stakeholder will access Dancier by a distinct Web-Application via a Web-Client
-|===
+| SMTP-Server | Used to send emails to stakeholders
+| Web-Client | Each Stakeholder will access Dancier through a dedicated web application via a web client (web browser).
+|===

src/main/jbake/content/documentation/arc42/src/04_solution_strategy.adoc

@@ -1,14 +1,14 @@
 [[section-solution-strategy]]
 == Solution Strategy
 
-Dancier will use best of breed technology and best practices in achieving it's functional goals:
+Dancier will leverage best-of-breed technology and best practices to achieve its functional goals:
 
-* By developing a web-application with responsive web design will enable all users on all devices (Phone,Tablet,Desktop) to access Dancier.
+* By developing a web application with responsive web design, we enable all users on all devices (Phone, Tablet, Desktop) to access Dancier.
 
-* By using well established technology based on Python/Spark we support well working recommendation algorithms to give the dancers that best fitting other dancers, events, course and workshops.
+* By using well established technology based on Python/Spark, we support well-working recommendation algorithms to give dancers the best-fitting counterparts for other dancers, events, courses, and workshops.
 
-* By using Java, Spring-Boot and PostgreSQL, we are using top established Technology for our backend services.
+* By using Java, Spring-Boot, and PostgreSQL, we leverage established technology for our backend services.
 
-* By using Kafka, we decouple services where appropriate, eg. to achieve a higher resilience
+* By using Kafka, we decouple services where appropriate, e.g. to achieve a higher resilience.
 
-* By developing everything as K8s-ready as possible we aim to be able to scale with our certainly growing user-base.
+* By developing everything as K8s-ready as possible, we aim to be able to scale with our certainly growing user base.

src/main/jbake/content/documentation/arc42/src/05_building_block_view.adoc

@@ -16,15 +16,15 @@ See the following sections for a brief description of each black box.
 [cols="h,4", stripes=none]
 |===
 |Purpose
-|Single Page Application, written in Angular, that contains the UIs for all parts of our system (Dancers, Schools,…​)
+|Single Page Application, written in Angular, that contains the UI for all parts of our system (Dancers, Schools,…​)
 
 |Interface
-|Web-Interface to be used with normal Web-Browsers. By using responsive web design methods, we make Dancier accessible to almost any device that runs a web browser.
+|Web interface designed for use with standard web browsers. Utilizing responsive web design methods ensures Dancier's accessibility on nearly any device with a web browser.
 
 Connect to the "Dancer" with our <<BBF>>.
 
 |Risks
-|Could become a frontend monolith, as it handles the UI for really everything.
+|Could evolve into a frontend monolith that is hard to maintain. We have to be careful to keep the codebase clean and modular while we add new features to the UI.
 
 |Repo
 |https://github.com/dancier/show-dancer
@@ -35,19 +35,19 @@ Connect to the "Dancer" with our <<BBF>>.
 [cols="h,4", stripes=none]
 |===
 |Purpose
-|<<BBF>> to Dancier. All calls from the internet are handled by this component. Additionally, it also handles the User/Account/Profile management. This is the case as we started with a monolithic approach for Dancier, putting everything in one modular monolith. Having the mentioned functionalities included in Dancier, actually makes no problems, so we stick to this.
+|<<BBF>> to Dancier. All calls from the internet are handled by this component. Additionally, it's also responsible for user/account/profile management. We started with a monolithic approach for Dancer, putting everything in one modular monolith. Having the mentioned functionalities included in Dancer gave us no issues so far, so we continue with this approach.
 
 |Interface
-|The Dancer has a link:https://editor.swagger.io/?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdancier%2Fdancer%2Fmaster%2Fswagger.yaml[Rest-API] to let our Angular Single Page Application (SPA) communicate with the whole Dancier System.
+|Dancer provides a link:https://editor.swagger.io/?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdancier%2Fdancer%2Fmaster%2Fswagger.yaml[REST API], giving our Angular Single Page Application (SPA) an entrypoint to communicate with the entire Dancier System.
 
-See the link:https://project.dancier.net/documentation/arc42/index.html#whitebox_overall_system[whitebox overall system] to infer what services are used by the Dancer directly.
+Refer to the link:https://project.dancier.net/documentation/arc42/index.html#whitebox_overall_system[whitebox overall system] to identify the services used by Dancer directly.
 
-Additionally, the Dancer emits <<BusinessEvent>>s for every interesting use case the dancer is mainly responsible for. This means mostly the handling of accounts and user profiles. The Events are sent to an S3 Bucket and to Kafka to be picked up by other services, that need that information.
+Additionally, Dancer emits <<BusinessEvent>>s for every interesting use case it's primarily responsible for, particularly the handling of accounts and user profiles. These events are sent to an S3 Bucket and Kafka to be consumed by other services requiring this information.
 
 (The Dancer will forward also every event it receives via the REST Event Endpoing) it receives from the SPA, as it could not connect to Kafka.
 
 |Risks/Smells
-|The Dancer is something in between a pure Backend for Frontend and a little modulith, as it also contains some modules with business logic. This is the case because we initially wanted to start with a modulith instead of lots of Microservices. The current setup makes testing a little bit more cumbersome. In case this will be too tedious for us, we have to refactor that.
+|The Dancer is something in between a pure backend for frontend and a small modulith, as it also contains some modules with business logic. This hybrid design stems from the initial preference for a modulith over numerous microservices. The current setup may introduce some testing complexities, and if found too cumbersome over time, refactoring may be necessary.
 
 |Repo
 |https://github.com/dancier/dancer
@@ -58,14 +58,14 @@ Additionally, the Dancer emits <<BusinessEvent>>s for every interesting use case
 [cols="h,4", stripes=none]
 |===
 |Purpose
-|Identify all Pairs of dancers that are likely to constitute a good dancing couple and compute a <<score>> for them.
+|Identify all pairs of dancers that are likely to form a good dancing couple and compute a <<score>> for them.
 
 |Interface
 
-|The Recommendation System reads once a day, all profile updated events. Computes all scores new and offers them via a REST-Endpoint.
+|The Recommendation System reads all profile update events once a day, computes new scores, and offers them via a REST endpoint.
 
 |Risks
-|Computing Score only once a day could become too bad for our customers and we have to refactor to a degree, that you can call it more of a rewrite.
+|Computing scores only once a day could turn out to be insufficient to satify our customer's needs for receiving good recommendations. Because of this, we may need to refactor to a degree that could be considered more of a rewrite.
 
 |Repo
 |https://github.com/dancier/recommendation
@@ -77,14 +77,13 @@ Additionally, the Dancer emits <<BusinessEvent>>s for every interesting use case
 [cols="h,4", stripes=none]
 |===
 |Purpose
-|This is the backend for all chat-related functionality
+|This is the backend for all chat-related functionality.
 
 |Interface
-|Ist being invoked by the dancer via its REST-API to create/maintain chats. Write <<BusinessEvent>> to Kafka in all interesting cases like ChatCreated, and MessageReceived. They are meant to be consumed by other systems eg. to determine if you should write the customer an e-mail to inform him about a new chat message...
+|It's invoked by the Dancer via its REST API to create/maintain chats. It writes <<BusinessEvent>>s to Kafka that might be interesting for other services to consume, like ChatCreated or MessageReceived. Once use case for it could be for another services to determine if an email should be sent to inform the customer about a new chat message.
 
 |Risks
-|Maybe we could have found an open-source chat backend. We decided against it, as we considered the effort to integrate a third-party tool, could be on par with the effort to implement basic functionality. If this would be the case, then we would be more flexible with our solution.
-But this was mostly grounded and bare assumptions.
+|Choosing an open-source chat backend might have been an option. However, we opted against it, considering that the effort to integrate a third-party tool could be comparable to implementing the basic functionality we need ourselves. If this assumption holds true, our solution would be more flexible. However, this decision was mostly grounded in assumptions.
 
 |Repo
 |https://github.com/dancier/chat-dancer
@@ -97,20 +96,20 @@ But this was mostly grounded and bare assumptions.
 [cols="h,4", stripes=none]
 |===
 |Purpose
-|Determine when to send what kind of E-Mail to our stakeholders.
+|This component determines when to send specific emails to our stakeholders.
 
 |Interface
 
-a|Read Business Events from all other systems like:
+a|It consumes business events from all other systems, such as:
 
-* when a user logs in
-* when a user is active
-* when a user changes his profile
-* when there are new recommendations for a user
-* when a new chat message arrives for a user
+* a user logging in
+* a user being active on the platform
+* a user updating their profile
+* the recommendation system computing new scores
+* a user sending a message to another user
 * ...
 
-It then determines on certain rules, whether to send an email to the user or not.
+It then applies certain rules to decide whether to send an email to the user or not.
 
 
 |Repo
@@ -148,7 +147,7 @@ It then determines on certain rules, whether to send an email to the user or not
 [cols="h,4", stripes=none]
 |===
 |Purpose
-|Third-party SMTP-Server for outgoing E-mails.
+|Third-party SMTP-Server for outgoing emails.
 
 |===
 

src/main/jbake/content/technology-stack.adoc

@@ -18,16 +18,16 @@ It's a result of applying our https://project.dancier.net/technology-decision-pr
 [stripes=odd, grid=cols, frame=none, cols="2"]
 |===
 |Java +
- for general programming | 
- Python + 
+ for general programming |
+ Python +
  for data-related tasks and scripting |
 https://dev.java/[
 image:./images/logo-java.svg[alt="Java Logo",  width=100, height=100]]|
 https://www.python.org/[
 image:./images/logo-python.svg[alt="Python Logo",  width=100,height=100]]
 
 |Spring Boot +
- for Java microservices | 
+ for Java microservices |
  Flask +
  for Python microservices|
 
@@ -50,10 +50,10 @@ image:./images/logo-javascript.svg[alt="Javascript Logo",  width=100, height=100
 |
 https://www.typescriptlang.org/[
 image:./images/logo-typescript.svg[alt="Typescript Logo",  width=100, height=100]]
-|Angular + 
+|Angular +
 For our Single Page Application|  |
 https://angular.io/[
-image:./images/logo-angular.svg[alt="Angular Logo",  width=100, height=100]] |
+image:./images/logo-angular.png[alt="Angular Logo",  width=100, height=100]] |
 |===
 
 
@@ -72,32 +72,32 @@ image:./images/logo-docker.png[alt="Docker Logo", width=200, height=100]]
 
 
 |Cloud Init  +
-for bootstrapping cloud instances| Docker-Compose + 
-for development and deployment 
+for bootstrapping cloud instances| Docker-Compose +
+for development and deployment
 |https://cloud-init.io/[
 image:./images/logo-cloud-init.svg[alt="Cloud Init Logo", width=200, height=100]]
 |https://docs.docker.com/compose/[
 image:./images/logo-docker-compose.png[alt="Docker Compose Logo", width=200, height=100]]
- 
+
 
 |S3 - Minio +
-our S3 Bucket Implementation| Keycloak + 
+our S3 Bucket Implementation| Keycloak +
 our Iam System
 |https://min.io/[
 image:./images/logo-minio.png[alt="Minio Logo", width=100, height=100]]
 |https://www.keycloak.org/[
 image:./images/logo-keycloak.png[alt="Keycloak Logo",  width=100, height=100]]
 
-|Nginx + 
+|Nginx +
 for delivering our Angular App| Hetzner Cloud +
 Our cloud provider
 |https://www.nginx.com/[
 image:./images/logo-nginx.png[alt="Nginx Logo", width=100, height=100]]
 |https://www.hetzner.com/cloud[
 image:./images/logo-hetzner.svg[alt="Hetzner Logo", width=100, height=100]]
 
-|Elastic Stack + 
-for monitoring and logging| Traefik + 
+|Elastic Stack +
+for monitoring and logging| Traefik +
 Traffic routing and SSL-Handling
 |https://www.elastic.co/[
 image:./images/logo-elasticsearch.svg[alt="Elastic Logo", width=200, height=100]]
@@ -107,7 +107,7 @@ image:./images/logo-traefik.png[alt="Elastic Logo", width=200, height=100]]
 
 |GitHub +
 Version control/Tickets
-|GitHub Actions + 
+|GitHub Actions +
 CI/CD
 |https://github.com/[
 image:./images/logo-github.png[alt="Github Logo", width=100, height=100]]
@@ -125,9 +125,9 @@ image:./images/logo-kafka.svg[alt="Kafka Logo", width=100, height=100]]|
 
 [stripes=odd, grid=cols, frame=none, cols="2"]
 |===
-|Nextcloud + 
+|Nextcloud +
 Project coordination
-| Collabora Office + 
+| Collabora Office +
 Project coordination
 |https://nextcloud.com/[image:./images/logo-nextcloud.svg[alt="Nextcloud Logo", width=100, height=100]]
 |https://www.collaboraoffice.com/collabora-online-3/[image:./images/logo-collabora-online.svg[alt="Collabora Logo", width=100, height=100]]