Merge branch 'main' into #578-add-DRY-LG-03-04

README.adoc

@@ -72,7 +72,7 @@ Relevant::
   Relevance also includes ensuring that the goals are aligned with current industry standards, technologies, and practices to prepare learners for real-world challenges.
 
 Authoritative:: 
-  Learning goals should be based on established content, industry best practices, and proven research. 
+  Learning goals should be <<handling-references, based on established content>> industry best practices, and proven research. 
   This ensures that the curriculum is aligned with recognized standards and that students are learning concepts that are widely accepted and validated in the field of software architecture.
   Where possible and adequate, authorative sources shall be referenced.
 
@@ -456,4 +456,30 @@ To unify upper/lowercase within the (EN) version, we use the _Chicago manual of
 For the German (DE) version, we don't use punctuation at the end of bullet-list items, unless on ends-of-sentences.
 
 
+[[handling-references]]
+=== Based on Established Content And References
+We strive to base all content on established content by providing references to original sources.
 
+In practice, this means that we reference the original source of a learning goal, if it is based on a book, a paper, a standard or similar.
+We use a distinct section for every learning goal:
+
+
+```
+===== {references}
+<<starkelorz>>
+``` 
+
+Example (abbreviated)
+----
+[[LG-01-01]]
+==== LG 01-01: Discuss Definitions of Software Architecture (R1)
+
+Software architects know the commonalities of many definitions of software architecture:
+
+* ...
+* ...
+
+===== {references}
+<<iso42010>>, <<bass>>, <<kruchten>>, <<starkelorz>>
+
+----

docs/01-basics/00-basic-concepts.adoc

@@ -17,7 +17,3 @@ include::./LG-01-04.adoc[{include_configuration}]
 include::./LG-01-05.adoc[{include_configuration}]
 
 include::./LG-01-06.adoc[{include_configuration}]
-
-include::./99-basics-references.adoc[tags={bibrefs}]
-
-include::./LZ-01-06.adoc[{include_configuration}]

docs/01-basics/LG-01-01.adoc

@@ -1,22 +1,21 @@
 // tag::DE[]
 [[LG-01-01]]
-==== LZ 01-01: Definitionen von Softwarearchitektur diskutieren (R1)
+==== LZ 01-01: Definitionen von Softwarearchitektur verstehen (R1)
 
-Softwarearchitekt:innen kennen die Gemeinsamkeiten vieler Definitionen von Softwarearchitektur:
+Softwarearchitekt:innen kennen und verstehen die Gemeinsamkeiten vieler Definitionen von Softwarearchitektur:
 
 * {glossary_url}building-block[Komponenten/Bausteine] mit Schnittstellen und Beziehungen
 * Bausteine als allgemeiner Begriff, Komponenten als eine spezielle Ausprägung davon
 * Strukturen, {glossary_url}cross-cutting-concern[Querschnittsthemen], Prinzipien
-* Architekturentscheidungen und ihre Auswirkungen auf das gesamte System und
-  seinen Lebenszyklus
+* Architekturentscheidungen und ihre Auswirkungen auf das gesamte System und seinen Lebenszyklus
 
 // end::DE[]
 
 // tag::EN[]
 [[LG-01-01]]
-==== LG 01-01: Discuss Definitions of Software Architecture (R1)
+==== LG 01-01: Understand Definitions of Software Architecture (R1)
 
-Software architects know the commonalities of many definitions of software architecture:
+Software architects know and understand the commonalities of many definitions of software architecture:
 
 * {glossary_url}building-block[components/building blocks] with interfaces and relationships
 * building blocks as a general term, components as a special form thereof

docs/02-requirements/00-requirements.adoc

@@ -18,4 +18,3 @@ include::./LG-02-04.adoc[{include_configuration}]
 
 include::./LG-02-05.adoc[{include_configuration}]
 
-include::./99-requirements-references.adoc[tags={bibrefs}]

docs/02-requirements/01-requirements-duration-terms.adoc

@@ -3,7 +3,7 @@
 == Anforderungen und Randbedingungen
 
 |===
-| Dauer: 60 Min. | Übungszeit: 60 Min.
+| Dauer: 90 Min. | Übungszeit: 90 Min.
 |===
 
 === Zielsetzung
@@ -23,12 +23,12 @@ Qualität; Qualitätsmerkmale; DIN/ISO 25010; Q42; Qualitätsszenarien; Kompromi
 == Requirements and Constraints
 
 |===
-| Duration: 60 min. | Exercises: 60 min.
+| Duration: 90 min. | Exercises: 90 min.
 |===
 
 === Purpose
-This section deepens participants' understanding of stakeholder concerns, requirements, and system qualities in software architecture.
-Participants learn to identify stakeholders and their influence on architectural decisions, discerning conflicts and synergies in the context of development projects.
+This section deepens participants' understanding of stakeholder concerns, requirements, and qualities of software architecture.
+Participants learn to identify the influence of stakeholders on architectural decisions and to assess conflicts and synergies in the context of development projects.
 By exploring diverse requirements and constraints, they gain insight into effectively addressing stakeholders' needs and project constraints.
 Additionally, they recognize the significance of software system qualities as drivers for architectural design. 
 They can formulate such requirements using scenarios.

docs/02-requirements/LG-02-01.adoc

@@ -13,16 +13,15 @@ Beispiele für Stakeholder und ihre Anliegen (R3):
 | Produktmanagement
 | z.{nbsp}B. benötigte Zeit für die Umsetzung der Anforderungen
 
-| Projektmanagement
-| z. B. benötigte Zeit und Budget für die Umsetzung, verbundene Risiken des
-gewählten architekturellen Ansatzes
+| Entwicklungsteam
+| z. B. zu implementierende Komponenten und Schnittstellen, Protokolle, technische Anforderungen und Randbedingungen
 
-| Requirements Engineering, Fachbereiche
+| Requirements Engineering, Product-Owner, Businss-Analyse, Fachbereiche
 | z. B. Erfüllung der Anforderungen
 
-| Entwicklungsteam
-| z. B. zu implementierende Komponenten und Schnittstellen, Protokolle,
-technologische Einschränkungen
+| Projektmanagement
+| z. B. benötigte Zeit und Budget für die Umsetzung, verbundene Risiken des
+gewählten architekturellen Ansatzes
 
 | Qualitätssicherung und Test
 | z. B. isoliertes Testen von Komponenten
@@ -32,7 +31,8 @@ technologische Einschränkungen
 
 |===
 
-Softwarearchitekt:innen können potenzielle Konflikte zwischen kurz- und langfristigen Zielen erklären, um mögliche Konflikte (z.B., Geschäfts- und Projektziele vs. Architektur- und Wartbarkeitsziele) zu lösen. (R2)
+Softwarearchitekt:innen können potenzielle Konflikte zwischen kurz- und langfristigen Zielen identifizieren (z.B. Geschäfts- und Projektziele vs. Architektur- und Wartbarkeitsziele).
+Sie verstehen, dass sie die relevanten Stakeholder einbeziehen müssen, um diese Konflikte zu lösen. (R2)
 
 Architekt:innen verstehen, dass nicht alle Anliegen der Stakeholder in Anforderungen umgesetzt werden können oder werden, aber dennoch berücksichtigt werden müssen. (R3)
 
@@ -53,14 +53,14 @@ Examples of stakeholders and concerns (R3):
 | product management and product owners
 | e.g., required time for the implementation of the requirements
 
-| project managers
-| e.g., required time and budget for the implementation, associated risks of the chosen architectural approach
+| developers
+| e.g., components and interfaces to be implemented, protocols, technical requirements and constraints
 
-| requirement engineers
+| requirement engineers, product owners, business analysts
 | e.g., fulfillment of the requirements
 
-| developers
-| e.g., components and interfaces to be implemented, protocols, technology constraints
+| project managers
+| e.g., required time and budget for the implementation, associated risks of the chosen architectural approach
 
 | quality assurance and testers
 | e.g., isolated testing of components
@@ -70,9 +70,11 @@ Examples of stakeholders and concerns (R3):
 
 |===
 
-Software architects can explain potential conflicts between short-term and long-term goals, in order to resolve potential conflicts (e.g., business and project goals vs. architecture and maintainability goals). (R2)
+Software architects can identify potential conflicts between short-term and long-term goals (e.g., business and project goals vs.
+architecture and maintainability goals).
+They understand that they need to involve the relevant stakeholders in order to resolve these conflicts. (R2)
 
-Architects understand that not all stakeholder concerns can or will be translated into requirements, but may nevertheless need to be considered. (R3)
+Architects understand that not all stakeholder concerns can or will be translated into requirements, but still need to be considered. (R3)
 
 Architects can use stakeholder concerns to discover missing or conflicting requirements and/or validate requirements and constraints on the architecture, e.g., in stakeholder interviews. (R3)
 

docs/02-requirements/LG-02-02.adoc

@@ -36,7 +36,7 @@ Sie erkennen und berücksichtigen den Einfluss von:
 
 * Trends wie (R3)
 ** Markttrends
-** Technologietrends (z.{nbsp}B. Blockchain, Microservices)
+** Technologietrends (z.{nbsp}B. Cloud, Microservices, Container, generative KI oder LLMs)
 ** Methodik-Trends (z.{nbsp}B. Agilität)
 ** (potenzielle) Auswirkungen weiterer Stakeholderinteressen und vorgegebener oder extern festgelegter Designentscheidungen 
 
@@ -45,7 +45,7 @@ Sie erkennen und berücksichtigen den Einfluss von:
 
 // tag::EN[]
 [[LG-02-02]]
-==== LG 02-02 [previously LG 2-3]: Identify and Consider Requirements and Constraints (R1-R3)
+==== LG 02-02 [previously LG 2-3]: Clarify and Consider Requirements and Constraints (R1-R3)
 
 Software architects understand that both requirements and constraints can have an impact on the architecture and the architecture work (R2).
 They are able to clarify requirements and constraints and take them into account in the architectural design and development process.
@@ -79,11 +79,9 @@ They should recognize and account for the impact of:
 
 * trends such as (R3)
 ** market trends
-** technology trends (Blockchain, Microservices)
-** methodology trends (Agile)
+** technology trends (e.g. cloud, microservices, container, generative AI or LLMs))
+** methodology trends (e.g. Agile)
 
-Software architects are able to describe how those factors can influence
-design decisions and can elaborate on the consequences of changing
-influencing factors by providing examples for some of them (R2).
+Software architects are able to describe how those factors can influence architecture decisions and can elaborate on the consequences of changing influencing factors by providing examples for some of them (R2).
 
 // end::EN[]

docs/02-requirements/LG-02-03.adoc

@@ -10,14 +10,12 @@ Softwarearchitekt:innen wissen dass der Begriff "Qualität" in verschiedenen Kon
 
 In diesem Lernziel geht es um letzteres.
 
-Softwarearchitekt:innen können erklären:
-
-* dass es unterschiedliche Taxonomien gibt, die Qualitäten von
-  Softwaresystemen kategorisieren (wie z.{nbsp}B. <<iso25010>>,
-  <<bass>> oder <<q42>>)
-* dass manche Kategorisierungen zwischen Funktionalität und Qualität unterscheiden, wie zum Beispiel IREB <<IREBFoundation>>
-* dass Softwarearchitekt:innen die Qualitäten eines Softwaresystems beeinflussen können
-* dass die Veränderung einer Qualität andere so beeinflussen kann, dass Abwägungen notwendig werden, wie z.{nbsp}B.
+Softwarearchitekt:innen können erklären dass:
+
+* es unterschiedliche Taxonomien gibt, die Qualitäten von Softwaresystemen kategorisieren 
+* manche Kategorisierungen zwischen Funktionalität und Qualität unterscheiden, wie zum Beispiel IREB <<IREBFoundation>>
+* Softwarearchitekt:innen die Qualitäten eines Softwaresystems beeinflussen können
+* die Veränderung einer Qualität andere so beeinflussen kann, dass Abwägungen notwendig werden, wie z.{nbsp}B.
 ** Konfigurierbarkeit versus Zuverlässigkeit
 ** Speicherbedarf versus Leistungseffizienz
 ** Sicherheit versus Benutzbarkeit
@@ -26,32 +24,39 @@ Softwarearchitekt:innen können erklären:
 
 Sie verstehen, dass 
 
-* eine einzelne Anforderung sich auf mehrere Qualitäten beziehen kann.
+* manche Kategorisierungen zwischen Qualitätsanforderungen und funktionalen Anforderungen unterscheiden, wie zum Beispiel IREB
+* sich eine einzelne Anforderung auf mehrere Qualitäten beziehen kann.
 // end::DE[]
 
 
 // tag::EN[]
 [[LG-02-03]]
 ==== LG 02-03 [previously LG 4-1]: Understand and Explain Qualities of a Software System (R1)
 
-Software architects know that the term "quality" is used differently in different contexts: 
+Software architects know that the term "quality" is used differently in different contexts:
+
 * referring to "excellence" in the context of quality management, and
 * referring to a "specific property (of a software system)" in others.
 
 This learning goal refers to the latter.
 
-They can explain
+Software architects can explain that:
 
-* that several taxonomies categorizing qualities of software systems exist (such as <<iso25010>>, <<bass>>, or <<q42>>)
-* that some categorizations distinguish between functionality and quality, e.g. IREB <<IREBFoundation>
-* that software architecture can impact a software system's qualities,
-* that impacting one quality can impact others, necessitating trade-offs, such as:
+* several taxonomies categorizing qualities of software systems exist
+* some categorizations distinguish between functionality and quality, e.g. IREB <<IREBFoundation>>
+* software architecture can impact a software system's qualities,
+* impacting one quality can impact others, necessitating trade-offs, such as:
 ** configurability versus reliability
 ** memory requirements versus performance efficiency
 ** security versus usability
 ** runtime flexibility versus maintainability.
 
 They understand that
 
+* some categorizations distinguish between quality requirements and functional requirements, e.g. IREB
 * a single requirement might pertain to several qualities
 // end::EN[]
+
+===== {references}
+
+<<IREBFoundation>>, <<iso25010>>, <<bass>>, <<q42>>

docs/02-requirements/LG-02-04.adoc

@@ -5,7 +5,7 @@
 
 Softwarearchitekt:innen:
 
-* können Szenarien für gegebene Qualitäten mit Kontext, Stimulus und Reaktion oder Messmethode formulieren <<bass>> (R1)
+* können Szenarien für gegebene Qualitäten mit Kontext, Stimulus und Reaktion oder Messmethode formulieren  (R1)
 * verstehen, dass eine Anforderung für eine gegebene Qualität
   eine Analysemethode spezifizieren sollte (siehe <<LG-05-02>>) (R1)
 * wissen, dass die Verwendung einer Metrik als Ziel diese invalidieren kann (R2), wie z.{nbsp}B. in Goodhart's Law (R3) beschrieben
@@ -18,8 +18,11 @@ Softwarearchitekt:innen:
 
 Software architects:
 
-* can formulate scenarios for given qualities containing context, stimulus, and reaction or method of measurement <<bass>> (R1)
+* can formulate scenarios for given qualities containing context, stimulus, and reaction or method of measurement  (R1)
 * understand that a requirement for a given quality should specify a method of analysis (see <<LG-05-02>>) (R1)
 * know that the use of a metric as a target can lead to its  invalidation (R2), as described, e.g., by Goodhart's law (R3)
 
 // end::EN[]
+
+===== {references}
+<<bass>>, <<q42>>, <<iso25010>>

docs/02-requirements/LG-02-05.adoc

@@ -16,6 +16,6 @@ Softwarearchitekt:innen:
 
 Software architects:
 
+* can make assumptions explicit and thus avoid implicit assumptions
 * know that implicit assumptions can lead to misunderstandings between stakeholders
-* assumptions should be made explicit
 // end::EN[]

docs/03-design/00-design.adoc

@@ -30,4 +30,3 @@ include::./LG-03-11.adoc[{include_configuration}]
 
 include::./LG-03-12.adoc[{include_configuration}]
 
-include::./99-design-references.adoc[tags={bibrefs}]

docs/03-design/01-design-duration-terms.adoc

@@ -4,7 +4,7 @@
 == Entwurf und Entwicklung von Softwarearchitekturen
 
 |===
-| Dauer: 330 Min. | Übungszeit: 90 Min.
+| Dauer: 270 Min. | Übungszeit: 90 Min.
 |===
 
 === Zielsetzung
@@ -18,15 +18,15 @@ Darüber hinaus werden in diesem Abschnitt der Umgang mit Querschnittsthemen, di
 
 Entwurf; 
 Vorgehen beim Entwurf; 
-Entwurfsentscheidung; 
+Architekturentscheidung; 
 Sichten; 
-Schnittstellen; 
+{glossary_url}interface[Schnittstellen];
 technische Konzepte und Querschnittsthemen; 
 Architekturmuster; 
 Entwurfsmuster; 
 Mustersprachen; 
 Entwurfsprinzipien; 
-Abhängigkeit; 
+Abhängigkeiten;
 Kopplung; 
 Kohäsion; 
 Top-down- und Bottom-up-Vorgehen;
@@ -40,7 +40,7 @@ Domain-Driven Design
 == Design and Development of Software Architectures
 
 |===
-| Duration: 330 min. | Excercises: 90 min.
+| Duration: 270 min. | Excercises: 90 min.
 |===
 
 === Purpose
@@ -51,11 +51,12 @@ They recognize the importance of design principles and solution patterns and are
 In addition, this section addresses the management of cross-cutting concerns, the principles of software deployment and the challenges of distributed systems.
 
 === Relevant Terms
-Design; design approach; design decision; views; 
+Design; design approach; architecture decision; views; 
 {glossary_url}interface[interfaces];  
-technical and 
+technical concepts and
 {glossary_url}cross-cutting-concern[cross-cutting concerns];
-architectural patterns; 
+architectural patterns;
+design patterns;
 pattern languages; 
 design principles; 
 dependencies;