From 9d57972ed103912e2cf8a7ea8efc2d7401c7a813 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Wed, 21 May 2025 19:15:37 +0200 Subject: [PATCH 01/24] Update README.adoc with workshop structure --- README.adoc | 80 +++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 65 insertions(+), 15 deletions(-) diff --git a/README.adoc b/README.adoc index 99aa570..26df5d9 100644 --- a/README.adoc +++ b/README.adoc @@ -1,33 +1,83 @@ -== Empty Repository += AsciiDoc für Software-Architektur Workshop +:toc: +:icons: font +:source-highlighter: highlight.js -This is just an empty repository to play around with some Diagrams-as-Code tools. +== Über diesen Workshop -To open this repository in gitpod, just preface the URL with `gitpod.io#`. +Dieser Workshop führt dich in die Dokumentation von Software-Architektur mit AsciiDoc und docToolchain ein. Du lernst, wie du das arc42-Template verwenden, Architekturdiagramme erstellen und Architekturentscheidungen dokumentieren kannst. -Next, gitpod will start a web based visual studio instance with everything pre-installed. +Die Übungen bauen aufeinander auf und vermitteln praktische Fähigkeiten für die Erstellung professioneller Architekturdokumentation. -Open this `README.adoc` and press `Ctrl+k` then `v` to aktivate the AsciiDoc preview. +== Voraussetzungen -Now open xref:src/docs/diagrams-as-code.adoc[] and start hacking. +* Grundlegende Kenntnisse in der Softwareentwicklung +* Git-Grundlagen +* Ein Texteditor mit AsciiDoc-Unterstützung (VSCode mit AsciiDoc-Plugin empfohlen) -''' +== Workshop-Struktur -=== advanced +Der Workshop ist in sechs Übungen gegliedert: -To install _docToolchain_, switch to the terminal and run +1. *Grundlagen-Setup und arc42-Template* - Einrichten der Umgebung und Kennenlernen des Templates +2. *AsciiDoc-Basics mit arc42-Fokus* - Grundlegende Syntax für Architektur-Dokumentation +3. *Diagramme mit PlantUML und C4* - Erstellung von Architekturdiagrammen als Code +4. *Architekturentscheidungen dokumentieren* - Struktur und Dokumentation von ADRs +5. *Qualitätsziele und Szenarien* - Definition und Dokumentation von Qualitätsanforderungen +6. *Kollaboration und CI/CD-Integration* - Teamarbeit an der Architekturdokumentation -[code, bash] +Alle Übungen befinden sich im Ordner `exercises/`. Lösungsbeispiele findest du im Ordner `solutions/`. + +== Erste Schritte + +1. Stelle sicher, dass docToolchain installiert ist: ++ +[source,bash] +---- +# Überprüfe, ob dtcw ausführbar ist +chmod +x dtcw + +# Zeige verfügbare Aufgaben an +./dtcw tasks --group doctoolchain +---- + +2. Öffne die erste Übung: ++ +[source] +---- +exercises/01_grundlagen_setup.adoc +---- + +3. Folge den Anweisungen in jeder Übungsdatei + +== Nützliche Ressourcen + +* xref:references.adoc[] - Hilfreiche Links und Cheat-Sheets +* xref:project-ideas.adoc[] - Ideen für Beispielprojekte, falls du kein eigenes Projekt hast + +== Für fortgeschrittene Teilnehmer + +Um docToolchain zu installieren, führe folgende Befehle aus: + +[source,bash] ---- -curl -Lo dtcw doctoolchain.github.io/dtcw +curl -Lo dtcw https://doctoolchain.org/dtcw chmod +x dtcw -./dtcw install +./dtcw local install java +./dtcw local install doctoolchain ---- -To preview the files, start a small server from within the terminal: +Um eine HTML-Vorschau zu starten: -[code, bash] +[source,bash] ---- python -m http.server 8000 ---- -Gitpod will now ask you what to do with the opened port. Just click on "open in browser" and navigate through the `build` folder. +Und navigiere dann zu `build/docs/html5`. + +== Über docToolchain + +docToolchain ist ein Open-Source-Tool zur Dokumentation als Code. Es nutzt das arc42-Template und AsciiDoc, um professionelle Architekturdokumentation zu erstellen. + +Mehr Informationen: https://doctoolchain.org \ No newline at end of file From ce101312845dc22d3d61bc8b030eda5de3fe86fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Wed, 21 May 2025 19:15:42 +0200 Subject: [PATCH 02/24] Create exercises directory with README --- exercises/README.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 exercises/README.md diff --git a/exercises/README.md b/exercises/README.md new file mode 100644 index 0000000..d4e14db --- /dev/null +++ b/exercises/README.md @@ -0,0 +1,3 @@ +# Übungen für den Workshop + +Dieser Ordner enthält alle Übungen für den Workshop. \ No newline at end of file From 5b1340683664d9adbb806fdd3184cab6245cc997 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Wed, 21 May 2025 19:15:46 +0200 Subject: [PATCH 03/24] Create solutions directory with README --- solutions/README.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 solutions/README.md diff --git a/solutions/README.md b/solutions/README.md new file mode 100644 index 0000000..35b363c --- /dev/null +++ b/solutions/README.md @@ -0,0 +1,3 @@ +# Lösungen für die Workshop-Übungen + +Dieser Ordner enthält Beispiellösungen für alle Workshop-Übungen. Versuche zunächst, die Übungen eigenständig zu lösen, bevor du dir die Lösungen ansiehst. \ No newline at end of file From 107381af43a74e21095a0a641a48ebc38cc5b465 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Wed, 21 May 2025 19:15:58 +0200 Subject: [PATCH 04/24] Add references.adoc with useful links --- references.adoc | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 references.adoc diff --git a/references.adoc b/references.adoc new file mode 100644 index 0000000..d711b6a --- /dev/null +++ b/references.adoc @@ -0,0 +1,47 @@ += Nützliche Referenzen +:toc: +:icons: font + +== AsciiDoc Referenzen + +* https://docs.asciidoctor.org/asciidoc/latest/[Offizielle AsciiDoc Dokumentation] +* https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc Syntax Quick Reference] +* https://powerman.name/doc/asciidoc[AsciiDoc Cheatsheet] + +== PlantUML & Diagramm-Referenzen + +* https://plantuml.com/[PlantUML Offizielle Website] +* https://c4model.com/[C4 Model für Software-Architektur] +* https://github.com/plantuml-stdlib/C4-PlantUML[C4-PlantUML Integration] +* https://kroki.io/[Kroki Diagramm-Rendering Service] + +== arc42 Referenzen + +* https://arc42.org/[arc42 Offizielle Website] +* https://docs.arc42.org/home/[arc42 Dokumentation] +* https://faq.arc42.org/home/[arc42 FAQ] +* https://arc42.org/overview[arc42 Template Übersicht] + +== docToolchain Referenzen + +* https://doctoolchain.org/[docToolchain Offizielle Website] +* https://doctoolchain.org/docToolchain/v2.0.x/[docToolchain Dokumentation] +* https://github.com/docToolchain/docToolchain[docToolchain GitHub Repository] + +== Architektur-Dokumentation Best Practices + +* https://leanpub.com/arc42byexample[arc42 by Example (eBook)] +* https://softwaredesign.remnote.io/[Software Architecture Playbook] +* https://leanpub.com/arc42inpractice/[Communicating Software Architectures with arc42 (eBook)] + +== ADR (Architecture Decision Records) + +* https://adr.github.io/[ADR GitHub Organization] +* https://github.com/joelparkerhenderson/architecture-decision-record[ADR Beispiele und Templates] +* https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions[Ursprünglicher ADR-Blogpost von Michael Nygard] + +== Weitere Ressourcen + +* https://docs-as-co.de/[Docs-as-Code Ressourcen] +* https://asciidoctor.org/docs/asciidoctor-pdf/[PDF-Erzeugung mit Asciidoctor] +* https://github.com/asciidoctor/asciidoctor-diagram[Asciidoctor Diagram Integration] From c798de5310dfac629ebfbd0f50ecddea69d043b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Wed, 21 May 2025 19:16:17 +0200 Subject: [PATCH 05/24] Add project-ideas.adoc with sample projects --- project-ideas.adoc | 102 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 project-ideas.adoc diff --git a/project-ideas.adoc b/project-ideas.adoc new file mode 100644 index 0000000..ac3e68b --- /dev/null +++ b/project-ideas.adoc @@ -0,0 +1,102 @@ += Projektideen +:toc: +:icons: font + +Wenn du kein eigenes Projekt für die Workshop-Übungen hast, kannst du eine der folgenden Projektideen verwenden. + +== DocHub: Dokumentations-Management-System + +*Beschreibung:* Ein zentrales System zur Verwaltung technischer Dokumentation für Software-Projekte. Unterstützt verschiedene Dokumentationsformate, Versionierung und automatische Generierung. + +*Hauptfunktionen:* +* Repository für verschiedene Dokumentationstypen (Benutzerhandbücher, API-Dokumentation, Architektur) +* Integration mit CI/CD-Pipelines +* Automatisches Rendering mehrerer Ausgabeformate (HTML, PDF, EPUB) +* Versionierung und Änderungsverfolgung +* Kommentar- und Review-Funktionen + +*Technologie-Stack:* +* Backend: Spring Boot (Java) +* Frontend: React mit TypeScript +* Datenbank: PostgreSQL +* Speicherung: MinIO (S3-kompatibel) +* CI/CD: GitHub Actions +* Dokumentation: AsciiDoc mit docToolchain + +== TaskMaster: Projektmanagement-Tool + +*Beschreibung:* Eine Anwendung zur Verwaltung von Projekten, Aufgaben und Teams mit Fokus auf Einfachheit und Integration. + +*Hauptfunktionen:* +* Projekt- und Aufgabenverwaltung (Kanban, Listen, Gantt-Charts) +* Zeit- und Ressourcenplanung +* Team-Kollaboration und Kommunikation +* Dokumentenmanagement und Wissensdatenbank +* Berichte und Dashboards + +*Technologie-Stack:* +* Backend: Node.js mit Express +* Frontend: Vue.js +* Datenbank: MongoDB +* Echtzeit-Kommunikation: WebSockets +* Authentifizierung: OAuth 2.0 +* Container: Docker & Kubernetes + +== SmartHome Control Center + +*Beschreibung:* Eine zentrale Plattform zur Steuerung und Überwachung verschiedener Smart-Home-Geräte, unabhängig vom Hersteller. + +*Hauptfunktionen:* +* Integration unterschiedlicher IoT-Geräte und Protokolle +* Automatisierte Abläufe und Szenarien +* Dashboards zur Visualisierung von Verbrauch und Status +* Alarmierung und Benachrichtigungen +* Mobile App und Sprachsteuerung + +*Technologie-Stack:* +* Backend: Python mit FastAPI +* Frontend: Angular +* Datenbank: InfluxDB (Zeitreihendaten) und Redis (Caching) +* Kommunikation: MQTT und REST +* Edge Computing: Raspberry Pi als lokaler Hub +* Containerisierung: Docker Compose + +== E-Learning Plattform + +*Beschreibung:* Eine modulare Lernplattform für die Erstellung, Verwaltung und Durchführung von Online-Kursen mit interaktiven Elementen. + +*Hauptfunktionen:* +* Kursverwaltung und Lernpfade +* Interaktive Inhalte (Videos, Quizze, Coding-Challenges) +* Fortschrittsverfolgung und Zertifizierung +* Soziale Funktionen (Diskussionen, Peer-Reviews) +* Analysen und Lernfortschritt + +*Technologie-Stack:* +* Backend: Django (Python) +* Frontend: Next.js (React) +* Datenbank: PostgreSQL +* Suche: Elasticsearch +* Medienverarbeitung: FFmpeg +* Deployment: AWS +* Authentifizierung: Keycloak + +== MicroStore: Microservices-E-Commerce-System + +*Beschreibung:* Ein modernes E-Commerce-System, das konsequent auf Microservices-Architektur setzt und damit hohe Skalierbarkeit und Flexibilität bietet. + +*Hauptfunktionen:* +* Produktkatalog und Suche +* Warenkorb und Bestellverwaltung +* Zahlungs- und Versandintegration +* Kundenverwaltung und Personalisierung +* Reporting und Analytics + +*Technologie-Stack:* +* Services: Spring Boot, Quarkus, Node.js (verschiedene Sprachen pro Service) +* Frontend: Angular mit wiederverwendbaren Microfrontends +* Datenbanken: Polyglot Persistence (PostgreSQL, MongoDB, Redis) +* Service Mesh: Istio +* API Gateway: Kong +* Event Streaming: Kafka +* Überwachung: Prometheus und Grafana From 403cda3e98e0643a30e3ba7774dc093f8008ca4d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Wed, 21 May 2025 19:16:36 +0200 Subject: [PATCH 06/24] Add Exercise 1: Basic Setup and arc42 Template --- exercises/01_grundlagen_setup.adoc | 95 ++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 exercises/01_grundlagen_setup.adoc diff --git a/exercises/01_grundlagen_setup.adoc b/exercises/01_grundlagen_setup.adoc new file mode 100644 index 0000000..13eef2d --- /dev/null +++ b/exercises/01_grundlagen_setup.adoc @@ -0,0 +1,95 @@ += Übung 1: Grundlagen-Setup und arc42-Template +:toc: +:icons: font +:source-highlighter: highlight.js + +== Was du lernst +* docToolchain-Wrapper verwenden +* arc42-Template herunterladen und rendern +* Basisstruktur einer AsciiDoc-Datei verstehen + +== Beschreibung + +In dieser ersten Übung wirst du mit docToolchain vertraut und erstellst deine erste arc42-Dokumentation. +Du wirst lernen, wie du das arc42-Template herunterlädst und es mit docToolchain renderst. + +== Beispiel: docToolchain initialisieren + +Der docToolchain-Wrapper `dtcw` ist bereits installiert. So kannst du verfügbare Aufgaben anzeigen: + +[source,bash] +---- +# docToolchain-Wrapper ausführbar machen +chmod +x dtcw + +# Verfügbare Aufgaben anzeigen +./dtcw tasks --group doctoolchain +---- + +Beispiel für die Grundstruktur einer einfachen AsciiDoc-Datei: + +[source,asciidoc] +---- += Dokumententitel +:toc: // Aktiviert das Inhaltsverzeichnis +:icons: font // Verwendet Font Icons +:sectnums: // Aktiviert Abschnittsnummerierung + +== Erster Abschnitt + +Dies ist ein Absatz im ersten Abschnitt. + +* Ein Listenpunkt +* Noch ein Listenpunkt + +== Zweiter Abschnitt + +=== Unterabschnitt + +Ein Link zu einem anderen Abschnitt: <> +---- + +== Deine Aufgabe + +1. Mache dich mit dem Repository vertraut +2. Führe den docToolchain-Wrapper aus und lade das arc42-Template herunter: + * `./dtcw downloadTemplate` + * Wähle Option 1 (arc42) + * Wähle EN als Sprache + * Wähle "plain" als Variante + * Bei der Frage nach Antora, wähle "n" (nein) +3. Generiere HTML aus dem Template: + * `./dtcw generateHTML` +4. Öffne die generierte HTML-Datei aus dem build/docs/html5-Verzeichnis +5. Öffne die Datei `src/docs/arc42/index.adoc` und passe den Titel an: + * Ändere den Titel zu einem aussagekräftigen Namen für dein Projekt + * Passe auch die Autoren und andere Metadaten an +6. Generiere die HTML-Datei erneut und prüfe deine Änderung + +== Automatisierung des downloadTemplate-Befehls + +Für CI/CD-Pipelines oder zur Automatisierung kannst du den `downloadTemplate`-Befehl mit vordefinierten Antworten ausführen: + +[source,bash] +---- +# Für Linux/macOS (Bash) +echo -e "1\nEN\nplain\nn" | ./dtcw downloadTemplate + +# Für Windows (Command Prompt) +(echo 1 & echo EN & echo plain & echo n) | .\dtcw.bat downloadTemplate + +# Für Windows (PowerShell) +"1`nEN`nplain`nn" | .\dtcw.ps1 downloadTemplate +---- + +== Bonusaufgabe +Generiere auch eine PDF-Version des Templates mit `./dtcw generatePDF` + +== Weiterführende Links + +* https://arc42.org/overview[arc42 Template Übersicht] +* https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc Syntax Schnellreferenz] + +== Nächste Schritte + +Öffne die nächste Übung: `exercises/02_asciidoc_basics.adoc` From 11af7e3856f540126a6b240dd82108a16153bf00 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Wed, 21 May 2025 19:22:51 +0200 Subject: [PATCH 07/24] Add Exercise 2: AsciiDoc Basics with arc42 Focus --- exercises/02_asciidoc_basics.adoc | 136 ++++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 exercises/02_asciidoc_basics.adoc diff --git a/exercises/02_asciidoc_basics.adoc b/exercises/02_asciidoc_basics.adoc new file mode 100644 index 0000000..7a68702 --- /dev/null +++ b/exercises/02_asciidoc_basics.adoc @@ -0,0 +1,136 @@ += Übung 2: AsciiDoc-Basics mit arc42-Fokus +:toc: +:icons: font +:source-highlighter: highlight.js + +== Was du lernst +* AsciiDoc-Syntax für Kapitelstruktur, Listen, Tabellen +* arc42-Abschnitte mit Inhalt füllen +* Querverweise zwischen arc42-Abschnitten erstellen + +== Beschreibung + +In dieser Übung lernst du, wie du AsciiDoc-Syntax für die Erstellung von Architekturdokumentation im arc42-Format verwendest. Du wirst lernen, wie du die verschiedenen Elemente von AsciiDoc nutzt, um eine strukturierte und gut lesbare Dokumentation zu erstellen. + +== Beispiel: Kapitel 1 (Einführung) bearbeiten + +Hier ist ein Beispiel, wie du das Kapitel 1 (Einführung und Ziele) mit AsciiDoc gestalten kannst: + +[source,asciidoc] +---- +== Einführung und Ziele + +=== Aufgabenstellung +Unser System soll es ermöglichen, Dokumentation als Code zu behandeln und folgende Ziele zu erreichen: + +* Versionsverwaltung für Dokumentation +* Automatisierte Builds der Dokumentation +* Kollaborative Bearbeitung durch das Entwicklungsteam + +=== Qualitätsziele + +[cols="1,2,2", options="header"] +|=== +| Priorität | Qualitätsziel | Motivation +| 1 | Wartbarkeit | Dokumentation soll leicht zu aktualisieren sein +| 2 | Aktualität | Dokumentation soll mit Code synchron bleiben +| 3 | Zugänglichkeit | Für alle Stakeholder leicht auffindbar +|=== + +=== Stakeholder + +Siehe <> für Details. +---- + +=== Weitere AsciiDoc-Elemente für die Architekturdokumentation + +==== Hervorhebungen + +[source,asciidoc] +---- +*fett* für wichtige Begriffe +_kursiv_ für Betonung +`monospace` für Code oder technische Begriffe +---- + +==== Info-Blöcke + +[source,asciidoc] +---- +[NOTE] +==== +Dies ist ein Hinweis für den Leser. +==== + +[TIP] +==== +Dies ist ein Tipp oder eine Best Practice. +==== + +[IMPORTANT] +==== +Dies ist eine wichtige Information, die beachtet werden sollte. +==== + +[WARNING] +==== +Dies ist eine Warnung vor möglichen Problemen. +==== + +[CAUTION] +==== +Dies ist ein Hinweis auf besondere Vorsicht. +==== +---- + +==== Querverweise + +[source,asciidoc] +---- +Siehe <> für weitere Details. + +[[section-id]] +=== Abschnittsüberschrift +---- + +== Deine Aufgabe + +1. Öffne die Datei `src/docs/arc42/01_introduction_and_goals.adoc` +2. Fülle die Abschnitte mit Inhalt für ein fiktives Software-Projekt deiner Wahl + * Beschreibe die Aufgabenstellung des Projekts + * Definiere 3-5 Qualitätsziele + * Liste wichtige Stakeholder auf +3. Erstelle eine aussagekräftige Tabelle für Qualitätsziele mit Prioritäten +4. Füge mindestens vier Stakeholder hinzu (mit Rollen und Erwartungen) +5. Erstelle einen Querverweis zu einem anderen Kapitel (z.B. zu Randbedingungen) +6. Generiere HTML und überprüfe deine Änderungen + +=== Stakeholder-Tabelle Beispiel + +[source,asciidoc] +---- +[cols="1,2,2", options="header"] +|=== +| Rolle | Kontakt | Erwartungen +| Produktmanager | Max Mustermann | Klare Darstellung der Systemfunktionen +| Entwicklungsteam | Team Alpha | Technische Details und Begründungen +| Support | Support-Abteilung | Betriebsaspekte und Fehlerbehebung +| Endbenutzer | Fachabteilung | Einfaches Verständnis der Grundfunktionen +|=== +---- + +== Bonusaufgabe +Nutze verschiedene AsciiDoc-Formatierungen wie: +* Infoboxen (NOTE, TIP, IMPORTANT, WARNING, CAUTION) +* Hervorhebungen (*fett*, _kursiv_, `Code`) +* Quellcode-Blöcke mit Syntax-Highlighting +* Nummerierte Listen für Prioritäten oder Prozessschritte + +== Weiterführende Links + +* https://docs.asciidoctor.org/asciidoc/latest/[AsciiDoc Dokumentation] +* https://docs.arc42.org/section-1/[arc42 Einführung und Ziele] + +== Nächste Schritte + +Öffne die nächste Übung: `exercises/03_diagramme_plantuml_c4.adoc` From 10f48e8da1b2528c6304a688768966e9529dda23 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Wed, 21 May 2025 19:23:19 +0200 Subject: [PATCH 08/24] Add Exercise 3: Diagrams with PlantUML and C4 --- exercises/03_diagramme_plantuml_c4.adoc | 159 ++++++++++++++++++++++++ 1 file changed, 159 insertions(+) create mode 100644 exercises/03_diagramme_plantuml_c4.adoc diff --git a/exercises/03_diagramme_plantuml_c4.adoc b/exercises/03_diagramme_plantuml_c4.adoc new file mode 100644 index 0000000..10f6864 --- /dev/null +++ b/exercises/03_diagramme_plantuml_c4.adoc @@ -0,0 +1,159 @@ += Übung 3: Diagramme mit PlantUML und C4 +:toc: +:icons: font +:source-highlighter: highlight.js + +== Was du lernst +* PlantUML-Diagramme in arc42 integrieren +* C4-Modell für Architekturdiagramme +* Kontext- und Container-Diagramme erstellen + +== Beschreibung + +In dieser Übung lernst du, wie du aussagekräftige Architekturdiagramme mit PlantUML und dem C4-Modell erstellst und in deine arc42-Dokumentation einbindest. Diagramme sind ein wesentlicher Bestandteil guter Architekturdokumentation und helfen dabei, komplexe Systeme verständlich darzustellen. + +== Das C4-Modell + +Das C4-Modell wurde von Simon Brown entwickelt und bietet einen hierarchischen Ansatz zur Visualisierung von Softwarearchitekturen mit vier Abstraktionsebenen: + +1. *Context* - Das Gesamtsystem und seine Beziehung zu Benutzern und externen Systemen +2. *Container* - Die Hauptkomponenten des Systems (Anwendungen, Datenbanken, etc.) +3. *Component* - Die Komponenten innerhalb eines Containers +4. *Code* - Die Implementierungsdetails (Klassen, Funktionen, etc.) + +== Beispiel: Kontext-Diagramm mit PlantUML/C4 + +[source,asciidoc] +---- +[plantuml,"system-context-diagram",png] +---- +!include + +title System Context Diagram for DocSystem + +Person(user, "Technical Writer", "Erstellt und pflegt technische Dokumentation") +Person(developer, "Developer", "Entwickelt Software und aktualisiert Docs") + +System(docSystem, "Documentation System", "Ermöglicht die Verwaltung von Dokumentation als Code") + +System_Ext(vcs, "Version Control", "Speichert alle Dokument-Versionen") +System_Ext(ci, "CI/CD Pipeline", "Automatisiert Builds und Veröffentlichungen") + +Rel(user, docSystem, "Erstellt und verwaltet Dokumente") +Rel(developer, docSystem, "Aktualisiert technische Details") +Rel(docSystem, vcs, "Speichert Versionen") +Rel(docSystem, ci, "Triggert Builds") +---- +---- + +Das Ergebnis würde so aussehen: + +image::plantuml-context-example.png[Beispiel Kontext-Diagramm] + +== Beispiel: Container-Diagramm mit PlantUML/C4 + +[source,asciidoc] +---- +[plantuml,"container-diagram",png] +---- +!include + +title Container Diagram for Documentation System + +Person(user, "Technical Writer", "Erstellt und pflegt technische Dokumentation") +Person(developer, "Developer", "Entwickelt Software und aktualisiert Docs") + +System_Boundary(docSystem, "Documentation System") { + Container(webApp, "Web Application", "JavaScript, Angular", "Bietet Benutzeroberfläche für das Dokumentationssystem") + Container(api, "API Application", "Java, Spring Boot", "Stellt REST-API für die Dokumentationsverwaltung bereit") + Container(converter, "Doc Converter", "Python", "Konvertiert Dokumente in verschiedene Formate") + ContainerDb(db, "Database", "PostgreSQL", "Speichert Metadaten, Benutzer und Konfiguration") + Container(fileStore, "File Storage", "MinIO", "Speichert Dokumentdateien") +} + +System_Ext(vcs, "Version Control", "Speichert alle Dokument-Versionen") +System_Ext(ci, "CI/CD Pipeline", "Automatisiert Builds und Veröffentlichungen") + +Rel(user, webApp, "Nutzt", "HTTPS") +Rel(developer, webApp, "Nutzt", "HTTPS") +Rel(webApp, api, "API-Aufrufe", "JSON/HTTPS") +Rel(api, converter, "Konvertierungsaufträge", "RPC") +Rel(api, db, "Liest/Schreibt", "JDBC") +Rel(api, fileStore, "Liest/Schreibt Dateien", "S3 API") +Rel(api, vcs, "Commit/Push", "Git") +Rel(api, ci, "Triggert Build", "Webhook") +---- +---- + +== Deine Aufgabe + +1. Öffne die Datei `src/docs/arc42/03_system_scope_and_context.adoc` +2. Ergänze ein Kontext-Diagramm mit C4-Notation für dein Projekt + * Definiere mindestens 2 Personentypen + * Definiere mindestens 3 externe Systeme + * Stelle sinnvolle Beziehungen her +3. Öffne die Datei `src/docs/arc42/05_building_block_view.adoc` +4. Erstelle ein Container-Diagramm für dein System + * Zeige interne Container/Komponenten deines Systems + * Stelle Beziehungen zu externen Systemen und Personen her + * Verwende unterschiedliche Container-Typen (Webanwendung, API, Datenbank, etc.) +5. Generiere HTML und prüfe deine Diagramme + +== Tipps zur PlantUML/C4-Syntax + +=== Personen definieren + +[source,plantuml] +---- +Person(alias, "Label", "Optional Description") +Person_Ext(alias, "Label", "Optional Description") +---- + +=== Systeme definieren + +[source,plantuml] +---- +System(alias, "Label", "Optional Description") +System_Ext(alias, "Label", "Optional Description") +---- + +=== Container definieren + +[source,plantuml] +---- +Container(alias, "Label", "Technology", "Optional Description") +ContainerDb(alias, "Label", "Technology", "Optional Description") +---- + +=== Beziehungen definieren + +[source,plantuml] +---- +Rel(from, to, "Label", "Optional Technology") +Rel_Back(from, to, "Label", "Optional Technology") +Rel_Neighbor(from, to, "Label", "Optional Technology") +---- + +=== System-Grenzen definieren + +[source,plantuml] +---- +System_Boundary(alias, "Label") { + // Container innerhalb des Systems +} +---- + +== Bonusaufgabe +Erstelle ein Component-Diagramm für einen der wichtigsten Container/Module deines Systems. Zeige die internen Komponenten, ihre Beziehungen und Verantwortlichkeiten. + +== Weiterführende Links + +* https://c4model.com/[C4 Model für Software-Architektur] +* https://github.com/plantuml-stdlib/C4-PlantUML[C4-PlantUML Integration] +* https://plantuml.com/[PlantUML Offizielle Website] +* https://docs.arc42.org/section-3/[arc42 Kontext und Abgrenzung] +* https://docs.arc42.org/section-5/[arc42 Bausteinsicht] + +== Nächste Schritte + +Öffne die nächste Übung: `exercises/04_architekturentscheidungen.adoc` From 09936b476309c8aef1b253f7ff4fedf714ed99fe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Wed, 21 May 2025 19:23:48 +0200 Subject: [PATCH 09/24] Add Exercise 4: Documenting Architecture Decisions --- exercises/04_architekturentscheidungen.adoc | 132 ++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 exercises/04_architekturentscheidungen.adoc diff --git a/exercises/04_architekturentscheidungen.adoc b/exercises/04_architekturentscheidungen.adoc new file mode 100644 index 0000000..f4013f5 --- /dev/null +++ b/exercises/04_architekturentscheidungen.adoc @@ -0,0 +1,132 @@ += Übung 4: Architekturentscheidungen dokumentieren +:toc: +:icons: font +:source-highlighter: highlight.js + +== Was du lernst +* Architekturentscheidungen strukturiert dokumentieren +* Pugh-Matrix für Entscheidungsfindung nutzen +* ADRs ins arc42-Template integrieren + +== Beschreibung + +In dieser Übung lernst du, wie du Architekturentscheidungen (Architecture Decision Records, ADRs) strukturiert dokumentierst und in deine arc42-Dokumentation integrierst. Architekturentscheidungen sind ein wichtiger Bestandteil der Architekturdokumentation, da sie die Gründe für bestimmte Architekturansätze transparent machen und für zukünftige Teams nachvollziehbar halten. + +== Warum Architekturentscheidungen dokumentieren? + +* Nachvollziehbarkeit für zukünftige Teams und neue Teammitglieder +* Vermeidung von wiederholten Diskussionen über bereits getroffene Entscheidungen +* Verbesserung der Qualität von Entscheidungen durch strukturierten Prozess +* Transparenz über Abwägungen und Alternativen +* Identifikation von Risiken und technischen Schulden + +== Beispiel: ADR-Template für eine Datenbankauswahl + +[source,asciidoc] +---- +== ADR-001: Auswahl der Datenbankarchitektur + +|=== +| Datum: | 15.05.2025 +| Autoren: | Workshop-Team +| Status: | Vorgeschlagen +|=== + +=== Problemstellung und Kontext + +Wir benötigen eine Datenbank für die Speicherung von Dokumentationsmetadaten und Versionshistorie. +Die Datenbank muss skalierbar, wartbar und mit unseren bestehenden Systemen kompatibel sein. + +=== Alternativen-Bewertung (Pugh-Matrix) + +|=== +| Kriterium | Relationale DB (Baseline) | NoSQL Dokumenten-DB | Graph-DB +| Leistung bei komplexen Abfragen | 0 | -1 | +1 +| Skalierbarkeit | 0 | +1 | 0 +| Wartbarkeit | 0 | 0 | -1 +| Team-Expertise | 0 | +1 | -1 +| Infrastruktur-Kosten | 0 | 0 | -1 +| *Gesamtpunktzahl* | 0 | +1 | -2 +|=== + +=== Entscheidung + +Wir haben uns für eine dokumentenorientierte NoSQL-Datenbank (MongoDB) entschieden. + +=== Konsequenzen + +==== Positive Auswirkungen +- Bessere Skalierbarkeit für wachsende Dokumentationsanforderungen +- Flexibles Schema für unterschiedliche Dokumenttypen +- Gute Integration mit JavaScript/Node.js + +==== Risiken +- Komplexere Abfragen könnten langsamer sein als in einer relationalen DB +- Mögliche Konsistenzprobleme bei verteilten Deployments + +==== Technische Schuld +- Migration vorhandener Daten aus dem alten System +- Entwicklung neuer Query-Patterns für komplexe Abfragen +---- + +== Pugh-Matrix erklärt + +Die Pugh-Matrix (auch Entscheidungsmatrix genannt) ist ein Tool zur strukturierten Bewertung von Alternativen: + +1. Definiere eine Baseline (üblicherweise die aktuelle Lösung oder die einfachste Alternative) +2. Bewerte jede Alternative im Vergleich zur Baseline: + * `-1` = schlechter als die Baseline + * `0` = gleich wie die Baseline + * `+1` = besser als die Baseline +3. Summiere die Punkte für jede Alternative +4. Die Alternative mit der höchsten Punktzahl ist oft die beste Wahl + +== Deine Aufgabe + +1. Erstelle einen Ordner `src/docs/arc42/09_architecture_decisions/` falls nicht vorhanden +2. Erstelle eine neue ADR-Datei für eine wichtige Architekturentscheidung deines Projekts + * z.B. Frontend-Framework, API-Design, Deployment-Strategie, Datenbankauswahl +3. Nutze das vorgegebene ADR-Format mit Pugh-Matrix + * Definiere eine sinnvolle Problemstellung + * Wähle mindestens 3 Alternativen zur Bewertung + * Lege 4-5 relevante Bewertungskriterien fest + * Führe die Bewertung mit der Pugh-Matrix durch + * Dokumentiere die Entscheidung und ihre Konsequenzen +4. Inkludiere die ADR in die Hauptdatei `src/docs/arc42/09_design_decisions.adoc` + * Nutze das `include`-Direktiv: `include::09_architecture_decisions/adr-001.adoc[]` +5. Generiere HTML und prüfe deine ADR + +=== Mögliche Themen für ADRs + +* Wahl des Frontend-Frameworks (React vs. Angular vs. Vue) +* Datenbankarchitektur (Relational vs. NoSQL vs. NewSQL) +* API-Design (REST vs. GraphQL vs. gRPC) +* Authentifizierung und Autorisierung (OAuth vs. JWT vs. SAML) +* Deployment-Strategie (VMs vs. Kubernetes vs. Serverless) +* Monitoring und Logging (ELK vs. Prometheus/Grafana vs. Cloud-Lösungen) +* Microservices vs. Monolith +* Event-Sourcing vs. traditionelles CRUD +* Caching-Strategie + +== Status-Werte für ADRs + +ADRs durchlaufen typischerweise verschiedene Status: + +* `Vorgeschlagen` - Die Entscheidung wurde vorgeschlagen, aber noch nicht formal akzeptiert +* `Akzeptiert` - Die Entscheidung wurde angenommen und wird umgesetzt +* `Abgelehnt` - Die Entscheidung wurde verworfen +* `Ersetzt` - Die Entscheidung wurde durch eine neuere ADR ersetzt +* `Veraltet` - Die Entscheidung ist nicht mehr relevant + +== Bonusaufgabe +Erstelle eine zweite ADR, die von der ersten abhängig ist, und stelle diese Abhängigkeit im Dokument dar. Zum Beispiel könnte nach der Entscheidung für MongoDB eine Entscheidung über die Caching-Strategie folgen, die auf dieser Datenbankwahl aufbaut. + +== Weiterführende Links + +* https://adr.github.io/[ADR GitHub Organization] +* https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions[Ursprünglicher ADR-Blogpost von Michael Nygard] +* https://docs.arc42.org/section-9/[arc42 Entwurfsentscheidungen] + +== Nächste Schritte + +Öffne die nächste Übung: `exercises/05_qualitaetsziele_szenarien.adoc` From ec6349ab577b538fb16118e3ce317357491535b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Wed, 21 May 2025 19:24:19 +0200 Subject: [PATCH 10/24] Add Exercise 5: Quality Goals and Scenarios --- exercises/05_qualitaetsziele_szenarien.adoc | 162 ++++++++++++++++++++ 1 file changed, 162 insertions(+) create mode 100644 exercises/05_qualitaetsziele_szenarien.adoc diff --git a/exercises/05_qualitaetsziele_szenarien.adoc b/exercises/05_qualitaetsziele_szenarien.adoc new file mode 100644 index 0000000..b17c0b0 --- /dev/null +++ b/exercises/05_qualitaetsziele_szenarien.adoc @@ -0,0 +1,162 @@ += Übung 5: Qualitätsziele und Szenarien +:toc: +:icons: font +:source-highlighter: highlight.js + +== Was du lernst +* Qualitätsbaum nach ISO 25010 erstellen +* Konkrete Qualitätsszenarien definieren +* Qualitätsanforderungen mit Architekturentscheidungen verknüpfen + +== Beschreibung + +In dieser Übung lernst du, wie du Qualitätsziele systematisch definierst und durch konkrete Szenarien präzisierst. Qualitätsziele sind neben den funktionalen Anforderungen die wichtigsten Treiber für architektonische Entscheidungen. Gut definierte Qualitätsszenarien machen abstrakte Qualitätsziele messbar und überprüfbar. + +== ISO 25010 Qualitätsmodell + +Das ISO 25010 Modell definiert acht Hauptkategorien von Softwarequalität: + +1. *Funktionale Eignung* - Vollständigkeit, Korrektheit, Angemessenheit +2. *Leistungseffizienz* - Zeitverhalten, Ressourcenverbrauch, Kapazität +3. *Kompatibilität* - Koexistenz, Interoperabilität +4. *Benutzbarkeit* - Erlernbarkeit, Bedienbarkeit, Fehlerrobustheit, Ästhetik +5. *Zuverlässigkeit* - Reife, Verfügbarkeit, Fehlertoleranz, Wiederherstellbarkeit +6. *Sicherheit* - Vertraulichkeit, Integrität, Nachweisbarkeit, Authentizität +7. *Wartbarkeit* - Modularität, Wiederverwendbarkeit, Analysierbarkeit, Änderbarkeit, Testbarkeit +8. *Übertragbarkeit* - Anpassbarkeit, Installierbarkeit, Austauschbarkeit + +== Beispiel: Qualitätsbaum + +[source,asciidoc] +---- +=== Qualitätsbaum + +[plantuml,"quality-tree",png] +---- +@startmindmap +* Qualität +** Wartbarkeit +*** Änderbarkeit +*** Testbarkeit +** Benutzerfreundlichkeit +*** Erlernbarkeit +*** Bedienbarkeit +** Zuverlässigkeit +*** Verfügbarkeit +*** Fehlertoleranz +** Effizienz +*** Antwortzeit +*** Ressourcenverbrauch +@endmindmap +---- +---- + +== Beispiel: Qualitätsszenarien + +Qualitätsszenarien konkretisieren Qualitätsziele und machen sie messbar. Ein gutes Qualitätsszenario enthält: + +* Qualitätsattribut (welcher Aspekt) +* Auslöser (was passiert) +* Umgebung (unter welchen Bedingungen) +* Artefakt (welcher Teil des Systems) +* Antwort (wie reagiert das System) +* Messgröße (wie wird der Erfolg gemessen) + +[source,asciidoc] +---- +=== Qualitätsszenarien + +==== Szenario 1: Schnelle Dokumentationsaktualisierung + +[cols="1,3"] +|=== +| Qualitätsattribut | Wartbarkeit/Änderbarkeit +| Auslöser | Ein Entwickler möchte technische Dokumentation aktualisieren +| Umgebung | Während der aktiven Entwicklung +| Artefakt | Architektur-Dokumentation +| Antwort | Änderung kann parallel zum Code eingecheckt werden +| Metrik | Update und Veröffentlichung in < 10 Minuten +|=== + +Diese Anforderung beeinflusste maßgeblich unsere Entscheidung für <>. + +==== Szenario 2: Systemverfügbarkeit bei hoher Last + +[cols="1,3"] +|=== +| Qualitätsattribut | Zuverlässigkeit/Verfügbarkeit +| Auslöser | Spitzenlasten von bis zu 5000 gleichzeitigen Benutzern +| Umgebung | Produktionssystem während Marketingkampagne +| Artefakt | Gesamtsystem +| Antwort | System bleibt voll funktionsfähig +| Metrik | Verfügbarkeit > 99.9%, Antwortzeit < 2 Sekunden +|=== + +Dieses Szenario führte zur Entscheidung für <>. +---- + +== Deine Aufgabe + +1. Öffne die Datei `src/docs/arc42/10_quality_requirements.adoc` +2. Erstelle einen Qualitätsbaum für dein Projekt + * Basiere ihn auf ISO 25010 oder einem anderen Qualitätsmodell + * Nutze PlantUML MindMap oder eine andere passende Darstellung + * Identifiziere 3-4 Hauptqualitätsziele und ihre Unterkategorien +3. Definiere mindestens 4 konkrete Qualitätsszenarien + * Nutze die vorgeschlagene Tabellenstruktur + * Stelle sicher, dass jedes Szenario messbar ist + * Decke unterschiedliche Qualitätsattribute ab +4. Priorisiere die Qualitätsszenarien + * Hohe Priorität (Muss erreicht werden) + * Mittlere Priorität (Sollte erreicht werden) + * Niedrige Priorität (Nice-to-have) +5. Verbinde jedes Szenario mit den relevanten ADRs durch Querverweise +6. Generiere HTML und prüfe deine Ergebnisse + +== Beispiele für Qualitätsszenarien + +=== Wartbarkeit/Änderbarkeit +* Ein Entwickler kann eine neue Komponente hinzufügen, ohne bestehende Komponenten zu modifizieren +* Nach einem Designfehler kann die Architektur in 2 Personentagen angepasst werden + +=== Leistungseffizienz +* Das System verarbeitet 1000 Transaktionen pro Sekunde bei normaler Last +* Die Antwortzeit für Suchanfragen beträgt maximal 500ms für 95% der Anfragen + +=== Sicherheit +* Ein Angreifer, der unbefugten Zugriff erlangt, kann keine personenbezogenen Daten einsehen +* Nach einem Sicherheitsvorfall kann das System in weniger als 30 Minuten wiederhergestellt werden + +=== Benutzbarkeit +* Ein neuer Benutzer kann die Hauptfunktionen ohne Schulung innerhalb von 10 Minuten nutzen +* Die Fehlerrate bei Dateneingabe sinkt durch Validierung auf unter 2% + +== Traceability-Matrix (Bonusaufgabe) + +Eine Traceability-Matrix zeigt, welche Architekturentscheidungen welche Qualitätsszenarien unterstützen: + +[source,asciidoc] +---- +=== Traceability-Matrix + +[cols="1,4*^", options="header"] +|=== +| ADR | Wartbarkeit | Verfügbarkeit | Sicherheit | Leistung +| ADR-001: NoSQL Datenbank | ++ | + | o | ++ +| ADR-002: Microservices | ++ | + | + | - +| ADR-003: JWT-Authentifizierung | o | o | ++ | + +| ADR-004: React Frontend | + | o | o | + +|=== + +Legende: ++ stark positiv, + positiv, o neutral, - negativ, -- stark negativ +---- + +== Weiterführende Links + +* https://iso25000.com/index.php/en/iso-25000-standards/iso-25010[ISO 25010 Standard] +* https://docs.arc42.org/section-10/[arc42 Qualitätsanforderungen] +* https://www.infoq.com/articles/atam-quality-attributes/[ATAM - Architecture Tradeoff Analysis Method] + +== Nächste Schritte + +Öffne die nächste Übung: `exercises/06_kollaboration_cicd.adoc` From 8b2cd285a654888e0dad8dc6cd3fd8240e0dbad0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Wed, 21 May 2025 19:27:08 +0200 Subject: [PATCH 11/24] Add Exercise 6: Collaboration and CI/CD Integration --- exercises/06_kollaboration_cicd.adoc | 238 +++++++++++++++++++++++++++ 1 file changed, 238 insertions(+) create mode 100644 exercises/06_kollaboration_cicd.adoc diff --git a/exercises/06_kollaboration_cicd.adoc b/exercises/06_kollaboration_cicd.adoc new file mode 100644 index 0000000..b750e4c --- /dev/null +++ b/exercises/06_kollaboration_cicd.adoc @@ -0,0 +1,238 @@ += Übung 6: Kollaboration und CI/CD-Integration +:toc: +:icons: font +:source-highlighter: highlight.js + +== Was du lernst +* Dokumentation für Teamarbeit strukturieren +* Workflows für kollaborative Dokumentation definieren +* CI/CD-Integration für automatisierte Dokumentations-Builds + +== Beschreibung + +In dieser Übung lernst du, wie du deine Architekturdokumentation effektiv im Team pflegen und durch automatisierte Prozesse aktuell halten kannst. Die Integration in CI/CD-Pipelines stellt sicher, dass deine Dokumentation stets auf dem neuesten Stand ist und mit jedem Release automatisch generiert wird. + +== Herausforderungen bei Teamarbeit an der Dokumentation + +Bei der kollaborativen Arbeit an Dokumentation treten oft folgende Herausforderungen auf: + +* Unklare Zuständigkeiten für verschiedene Dokumentationsteile +* Inkonsistente Formatierung und Struktur +* Veraltete Dokumentation, die nicht mit dem Code Schritt hält +* Mangelnde Nachvollziehbarkeit von Änderungen +* Schwierigkeiten bei Review-Prozessen + +== Bewährte Praktiken für kollaborative Dokumentation + +* *Klare Verantwortlichkeiten*: Definiere, wer für welche Teile der Dokumentation zuständig ist +* *Docs-as-Code*: Behandle Dokumentation wie Code mit Versionierung und Reviews +* *Automatisierte Builds*: Integriere Dokumentationsgenerierung in deine CI/CD-Pipeline +* *Nachvollziehbarkeit*: Nutze aussagekräftige Commit-Messages und strukturierte Pull Requests +* *Leitfäden und Vorlagen*: Stelle Dokumentationsrichtlinien bereit + +== Beispiel: GitHub-Workflow für Dokumentationsbuilds + +[source,yaml] +---- +name: Build Documentation + +on: + push: + branches: [ main ] + paths: + - 'src/docs/**' + pull_request: + branches: [ main ] + paths: + - 'src/docs/**' + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Set up JDK 17 + uses: actions/setup-java@v3 + with: + java-version: '17' + distribution: 'temurin' + + - name: Build Documentation + run: | + chmod +x dtcw + ./dtcw generateHTML + ./dtcw generatePDF + + - name: Upload HTML Documentation + uses: actions/upload-artifact@v3 + with: + name: documentation-html + path: build/docs/html5 + + - name: Upload PDF Documentation + uses: actions/upload-artifact@v3 + with: + name: documentation-pdf + path: build/docs/pdf +---- + +== Workflow für Dokumentationsänderungen + +Ein typischer Workflow für Dokumentationsänderungen könnte so aussehen: + +1. Erstelle einen Feature-Branch für deine Änderungen +2. Führe lokale Änderungen durch und prüfe die Vorschau +3. Reiche einen Pull Request ein +4. Warte auf Reviews und Feedback +5. Führe notwendige Anpassungen durch +6. Merge in den Hauptbranch nach Freigabe +7. Automatischer Build und Deployment der Dokumentation + +== Deine Aufgabe + +1. Erstelle einen Workflow für dein Team: + * Definiere, wer welche Teile der Dokumentation pflegt (z.B. nach Fachgebieten oder Komponenten) + * Lege einen Review-Prozess für Dokumentationsänderungen fest + * Beschreibe, wie und wann Aktualisierungen stattfinden sollen + * Dokumentiere diese Regeln in `src/docs/arc42/12_glossary.adoc` oder einer separaten Datei + +2. Erstelle eine GitHub Action für automatisierte Builds: + * Erstelle den Ordner `.github/workflows/` falls nicht vorhanden + * Erstelle eine Datei `.github/workflows/build-docs.yml` mit einem Workflow, der: + - Bei Änderungen an Dokumentationsdateien ausgelöst wird + - docToolchain aufruft, um HTML und PDF zu generieren + - Die Ergebnisse als Artifacts speichert + +3. Erweitere deine Dokumentation um einen Abschnitt "Für Mitwirkende": + * Erstelle eine neue Datei `src/docs/contributing.adoc` + * Beschreibe den Prozess für Beiträge zur Dokumentation + * Lege Richtlinien für Formatierung und Stil fest + * Erkläre, wie man die Dokumentation lokal generiert und prüft + * Füge Informationen zu Werkzeugen und Plugins hinzu + +4. Generiere HTML und prüfe deine Ergebnisse + +== Beispiel für contributing.adoc + +[source,asciidoc] +---- += Mitwirken an der Dokumentation +:toc: +:icons: font + +== Einführung + +Dieses Dokument beschreibt, wie du zur Architekturdokumentation unseres Projekts beitragen kannst. +Wir nutzen Docs-as-Code mit AsciiDoc und docToolchain. + +== Voraussetzungen + +* Git installiert und konfiguriert +* Java JDK 17 oder höher +* Text-Editor mit AsciiDoc-Unterstützung (empfohlen: Visual Studio Code mit AsciiDoc-Plugin) + +== Workflow für Beiträge + +1. Forke das Repository (externe Mitwirkende) oder erstelle einen Branch (Team-Mitglieder) +2. Führe Änderungen an den AsciiDoc-Dateien durch +3. Generiere die Dokumentation lokal mit `./dtcw generateHTML` und prüfe das Ergebnis +4. Committe deine Änderungen mit einer aussagekräftigen Commit-Message +5. Erstelle einen Pull Request mit detaillierter Beschreibung deiner Änderungen + +== Richtlinien + +=== Struktur + +* Halte dich an die arc42-Struktur +* Eine Datei pro arc42-Kapitel +* Nutze eindeutige Abschnitts-IDs für Querverweise + +=== Formatierung + +* Nutze aussagekräftige Überschriften +* Halte Sätze und Absätze kurz und prägnant +* Verwende Listen für Aufzählungen +* Nutze Tabellen für strukturierte Informationen +* Vermeide Umgangssprache und Jargon + +=== Diagramme + +* Erstelle Diagramme mit PlantUML +* Nutze C4-Modell für Architekturdiagramme +* Halte Diagramme einfach und fokussiert +* Stelle sicher, dass Diagramme einen klaren Zweck erfüllen + +== Lokale Vorschau + +So generierst du die Dokumentation lokal: + +[source,bash] +---- +./dtcw generateHTML +./dtcw generatePDF +---- + +Die generierte Dokumentation findest du in: +* HTML: `build/docs/html5/` +* PDF: `build/docs/pdf/` +---- + +== Beispiel für GitHub Pages Deployment + +Um deine Dokumentation auf GitHub Pages zu veröffentlichen, kannst du folgenden Workflow nutzen: + +[source,yaml] +---- +name: Deploy Documentation to GitHub Pages + +on: + push: + branches: [ main ] + paths: + - 'src/docs/**' + +jobs: + build-and-deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Set up JDK 17 + uses: actions/setup-java@v3 + with: + java-version: '17' + distribution: 'temurin' + + - name: Build Documentation + run: | + chmod +x dtcw + ./dtcw generateHTML + + - name: Deploy to GitHub Pages + uses: JamesIves/github-pages-deploy-action@v4 + with: + folder: build/docs/html5 + branch: gh-pages +---- + +== Bonusaufgabe +Erstelle ein Deployment-Skript, das die generierte Dokumentation auf GitHub Pages oder einen anderen Hosting-Dienst veröffentlicht. Verwende den obigen Workflow als Vorlage und passe ihn an deine Bedürfnisse an. + +== Weiterführende Links + +* https://docs.github.com/en/actions[GitHub Actions Dokumentation] +* https://docs.github.com/en/pages[GitHub Pages Dokumentation] +* https://doctoolchain.org/docToolchain/v2.0.x/020_tutorial/030_createGithubRepo.html[docToolchain GitHub Integration] + +== Abschluss des Workshops + +Herzlichen Glückwunsch! Du hast alle sechs Übungen des Workshops abgeschlossen und kennst nun die grundlegenden Techniken zur Erstellung professioneller Architekturdokumentation mit AsciiDoc und arc42. + +Um dein Wissen zu vertiefen, empfehlen wir: +* Wende das Gelernte auf ein eigenes Projekt an +* Experimentiere mit erweiterten Funktionen von docToolchain +* Erkunde weitere Integration mit CI/CD-Tools +* Beteilige dich an der docToolchain-Community + +Wir freuen uns über dein Feedback zum Workshop und wünschen dir viel Erfolg bei deinen zukünftigen Dokumentationsprojekten! From 091da5918fe8e91de8db0a1a50133fcf82596002 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Wed, 21 May 2025 19:27:26 +0200 Subject: [PATCH 12/24] Add solution example for Exercise 1 --- solutions/01_grundlagen_setup_solution.adoc | 141 ++++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 solutions/01_grundlagen_setup_solution.adoc diff --git a/solutions/01_grundlagen_setup_solution.adoc b/solutions/01_grundlagen_setup_solution.adoc new file mode 100644 index 0000000..50d0607 --- /dev/null +++ b/solutions/01_grundlagen_setup_solution.adoc @@ -0,0 +1,141 @@ += Lösung: Übung 1 - Grundlagen-Setup und arc42-Template +:toc: +:icons: font +:source-highlighter: highlight.js + +Diese Datei enthält eine Beispiellösung für die erste Übung. + +== Schritt 1: Initialisierung + +Zuerst machen wir den docToolchain-Wrapper ausführbar: + +[source,bash] +---- +chmod +x dtcw +---- + +Dann prüfen wir, welche Aufgaben verfügbar sind: + +[source,bash] +---- +./dtcw tasks --group doctoolchain +---- + +== Schritt 2: arc42-Template herunterladen + +Wir laden das arc42-Template mit folgenden Befehlen herunter: + +[source,bash] +---- +./dtcw downloadTemplate +---- + +Bei den Abfragen wählen wir: +* Option 1 (arc42) +* EN als Sprache +* "plain" als Variante +* "n" bei der Frage nach Antora + +Alternativ können wir den Befehl auch automatisieren: + +[source,bash] +---- +echo -e "1\nEN\nplain\nn" | ./dtcw downloadTemplate +---- + +== Schritt 3: HTML generieren + +Wir generieren eine HTML-Version des Templates mit folgendem Befehl: + +[source,bash] +---- +./dtcw generateHTML +---- + +Die generierte HTML-Datei finden wir unter `build/docs/html5/arc42/index.html`. + +== Schritt 4: Dokumentation anpassen + +Wir öffnen die Datei `src/docs/arc42/index.adoc` und aktualisieren folgende Inhalte: + +[source,asciidoc] +---- += image:arc42-logo.png[arc42] DocHub: Documentation Management System +// header +:doctype: book +:icons: font +:sectnums: +:toc: left +:toclevels: 3 +:toc-title: Table of Contents +:experimental: +:imagesdir: images +:tip-caption: 🚀 +:note-caption: ℹ️ +:important-caption: ⚠️ +:warning-caption: 🔥 +:caution-caption: 🔪 + +// additional style for arc42 help callouts +ifdef::basebackend-html[] +++++ + +++++ +endif::basebackend-html[] + +// horizontal line + +*** + +Version 1.0, Mai 2025 + +// numbering from here on +:numbered: + +<<<< +// 1. Einführung und Ziele +include::01_introduction_and_goals.adoc[] + +<<<< +// 2. Randbedingungen +include::02_architecture_constraints.adoc[] + +// ... weitere Includes ... +---- + +== Schritt 5: HTML erneut generieren + +Wir generieren die HTML-Datei erneut und prüfen unsere Änderungen: + +[source,bash] +---- +./dtcw generateHTML +---- + +== Bonusaufgabe: PDF generieren + +Wir generieren eine PDF-Version des Templates: + +[source,bash] +---- +./dtcw generatePDF +---- + +Die generierte PDF-Datei finden wir unter `build/docs/pdf/`. + +== Fazit + +In dieser Übung haben wir: +* docToolchain-Wrapper kennengelernt +* arc42-Template heruntergeladen und angepasst +* HTML- und PDF-Versionen der Dokumentation generiert +* Grundlegende Struktur einer AsciiDoc-Datei verstanden From 1b7dba669ca8a6330352b31d13fe71b5fcda8455 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Wed, 21 May 2025 19:45:46 +0200 Subject: [PATCH 13/24] Update README.adoc based on review comments --- README.adoc | 33 +++++---------------------------- 1 file changed, 5 insertions(+), 28 deletions(-) diff --git a/README.adoc b/README.adoc index 26df5d9..d26dc3f 100644 --- a/README.adoc +++ b/README.adoc @@ -1,7 +1,6 @@ = AsciiDoc für Software-Architektur Workshop :toc: :icons: font -:source-highlighter: highlight.js == Über diesen Workshop @@ -9,6 +8,8 @@ Dieser Workshop führt dich in die Dokumentation von Software-Architektur mit As Die Übungen bauen aufeinander auf und vermitteln praktische Fähigkeiten für die Erstellung professioneller Architekturdokumentation. +Der Workshop findet in einem GitHub Workspace statt. Damit wird ein VS Code im Browser geöffnet, und du erhältst sofort Zugriff auf einen Editor mit AsciiDoc-Preview-Funktion. + == Voraussetzungen * Grundlegende Kenntnisse in der Softwareentwicklung @@ -30,14 +31,11 @@ Alle Übungen befinden sich im Ordner `exercises/`. Lösungsbeispiele findest du == Erste Schritte -1. Stelle sicher, dass docToolchain installiert ist: +1. Stelle sicher, dass docToolchain funktioniert (es ist bereits vorinstalliert): + [source,bash] ---- -# Überprüfe, ob dtcw ausführbar ist -chmod +x dtcw - -# Zeige verfügbare Aufgaben an +# Zeige verfügbare Tasks an ./dtcw tasks --group doctoolchain ---- @@ -55,29 +53,8 @@ exercises/01_grundlagen_setup.adoc * xref:references.adoc[] - Hilfreiche Links und Cheat-Sheets * xref:project-ideas.adoc[] - Ideen für Beispielprojekte, falls du kein eigenes Projekt hast -== Für fortgeschrittene Teilnehmer - -Um docToolchain zu installieren, führe folgende Befehle aus: - -[source,bash] ----- -curl -Lo dtcw https://doctoolchain.org/dtcw -chmod +x dtcw -./dtcw local install java -./dtcw local install doctoolchain ----- - -Um eine HTML-Vorschau zu starten: - -[source,bash] ----- -python -m http.server 8000 ----- - -Und navigiere dann zu `build/docs/html5`. - == Über docToolchain docToolchain ist ein Open-Source-Tool zur Dokumentation als Code. Es nutzt das arc42-Template und AsciiDoc, um professionelle Architekturdokumentation zu erstellen. -Mehr Informationen: https://doctoolchain.org \ No newline at end of file +Mehr Informationen: https://doctoolchain.org From 5f82b705c7603472b0b5c563f870fb9c56898205 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Wed, 21 May 2025 19:46:11 +0200 Subject: [PATCH 14/24] Update project-ideas.adoc based on review comments --- project-ideas.adoc | 58 ++++++++++++++++++++++++++++++++++------------ 1 file changed, 43 insertions(+), 15 deletions(-) diff --git a/project-ideas.adoc b/project-ideas.adoc index ac3e68b..f8c3c2d 100644 --- a/project-ideas.adoc +++ b/project-ideas.adoc @@ -4,18 +4,42 @@ Wenn du kein eigenes Projekt für die Workshop-Übungen hast, kannst du eine der folgenden Projektideen verwenden. +== iSAQB BigSpender + +.Beschreibung +Das BigSpender-Projekt ist ein Beispiel aus der iSAQB CPSA-Advanced-Prüfung und eignet sich hervorragend als Übungsprojekt. + +.Kontext +Es handelt sich um ein Zahlungsabwicklungssystem, das mehrere Zahlungsmethoden unterstützt und international eingesetzt wird. + +.Hauptfunktionen +* Verarbeitung von Online-Zahlungen (Kreditkarte, Überweisung, digitale Geldbörsen) +* Transaktionsüberwachung und Betrugserkennung +* Internationale Währungsunterstützung +* Berichtswesen und Analytik + +.Technologie-Stack +* Backend: Java mit Spring Boot +* Datenbank: PostgreSQL +* Messaging: Apache Kafka +* Frontend: Angular +* Infrastruktur: Kubernetes + +Weitere Informationen findest du in der [originalen Aufgabenbeschreibung](https://www.isaqb.org/wp-content/uploads/2021/07/cpsa-a-aufgabe-BigSpender-1.5.pdf). + == DocHub: Dokumentations-Management-System -*Beschreibung:* Ein zentrales System zur Verwaltung technischer Dokumentation für Software-Projekte. Unterstützt verschiedene Dokumentationsformate, Versionierung und automatische Generierung. +.Beschreibung +Ein zentrales System zur Verwaltung technischer Dokumentation für Software-Projekte. Unterstützt verschiedene Dokumentationsformate, Versionierung und automatische Generierung. -*Hauptfunktionen:* +.Hauptfunktionen * Repository für verschiedene Dokumentationstypen (Benutzerhandbücher, API-Dokumentation, Architektur) * Integration mit CI/CD-Pipelines * Automatisches Rendering mehrerer Ausgabeformate (HTML, PDF, EPUB) * Versionierung und Änderungsverfolgung * Kommentar- und Review-Funktionen -*Technologie-Stack:* +.Technologie-Stack * Backend: Spring Boot (Java) * Frontend: React mit TypeScript * Datenbank: PostgreSQL @@ -25,16 +49,17 @@ Wenn du kein eigenes Projekt für die Workshop-Übungen hast, kannst du eine der == TaskMaster: Projektmanagement-Tool -*Beschreibung:* Eine Anwendung zur Verwaltung von Projekten, Aufgaben und Teams mit Fokus auf Einfachheit und Integration. +.Beschreibung +Eine Anwendung zur Verwaltung von Projekten, Aufgaben und Teams mit Fokus auf Einfachheit und Integration. -*Hauptfunktionen:* +.Hauptfunktionen * Projekt- und Aufgabenverwaltung (Kanban, Listen, Gantt-Charts) * Zeit- und Ressourcenplanung * Team-Kollaboration und Kommunikation * Dokumentenmanagement und Wissensdatenbank * Berichte und Dashboards -*Technologie-Stack:* +.Technologie-Stack * Backend: Node.js mit Express * Frontend: Vue.js * Datenbank: MongoDB @@ -44,16 +69,17 @@ Wenn du kein eigenes Projekt für die Workshop-Übungen hast, kannst du eine der == SmartHome Control Center -*Beschreibung:* Eine zentrale Plattform zur Steuerung und Überwachung verschiedener Smart-Home-Geräte, unabhängig vom Hersteller. +.Beschreibung +Eine zentrale Plattform zur Steuerung und Überwachung verschiedener Smart-Home-Geräte, unabhängig vom Hersteller. -*Hauptfunktionen:* +.Hauptfunktionen * Integration unterschiedlicher IoT-Geräte und Protokolle * Automatisierte Abläufe und Szenarien * Dashboards zur Visualisierung von Verbrauch und Status * Alarmierung und Benachrichtigungen * Mobile App und Sprachsteuerung -*Technologie-Stack:* +.Technologie-Stack * Backend: Python mit FastAPI * Frontend: Angular * Datenbank: InfluxDB (Zeitreihendaten) und Redis (Caching) @@ -63,16 +89,17 @@ Wenn du kein eigenes Projekt für die Workshop-Übungen hast, kannst du eine der == E-Learning Plattform -*Beschreibung:* Eine modulare Lernplattform für die Erstellung, Verwaltung und Durchführung von Online-Kursen mit interaktiven Elementen. +.Beschreibung +Eine modulare Lernplattform für die Erstellung, Verwaltung und Durchführung von Online-Kursen mit interaktiven Elementen. -*Hauptfunktionen:* +.Hauptfunktionen * Kursverwaltung und Lernpfade * Interaktive Inhalte (Videos, Quizze, Coding-Challenges) * Fortschrittsverfolgung und Zertifizierung * Soziale Funktionen (Diskussionen, Peer-Reviews) * Analysen und Lernfortschritt -*Technologie-Stack:* +.Technologie-Stack * Backend: Django (Python) * Frontend: Next.js (React) * Datenbank: PostgreSQL @@ -83,16 +110,17 @@ Wenn du kein eigenes Projekt für die Workshop-Übungen hast, kannst du eine der == MicroStore: Microservices-E-Commerce-System -*Beschreibung:* Ein modernes E-Commerce-System, das konsequent auf Microservices-Architektur setzt und damit hohe Skalierbarkeit und Flexibilität bietet. +.Beschreibung +Ein modernes E-Commerce-System, das konsequent auf Microservices-Architektur setzt und damit hohe Skalierbarkeit und Flexibilität bietet. -*Hauptfunktionen:* +.Hauptfunktionen * Produktkatalog und Suche * Warenkorb und Bestellverwaltung * Zahlungs- und Versandintegration * Kundenverwaltung und Personalisierung * Reporting und Analytics -*Technologie-Stack:* +.Technologie-Stack * Services: Spring Boot, Quarkus, Node.js (verschiedene Sprachen pro Service) * Frontend: Angular mit wiederverwendbaren Microfrontends * Datenbanken: Polyglot Persistence (PostgreSQL, MongoDB, Redis) From 791672da11f65f4f245e2cdbe7cf005c68ef5b4e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Wed, 21 May 2025 19:46:26 +0200 Subject: [PATCH 15/24] Update references.adoc based on review comments --- references.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/references.adoc b/references.adoc index d711b6a..d2a14a6 100644 --- a/references.adoc +++ b/references.adoc @@ -42,6 +42,5 @@ == Weitere Ressourcen -* https://docs-as-co.de/[Docs-as-Code Ressourcen] * https://asciidoctor.org/docs/asciidoctor-pdf/[PDF-Erzeugung mit Asciidoctor] * https://github.com/asciidoctor/asciidoctor-diagram[Asciidoctor Diagram Integration] From fa4216e3a4f61c4d02a30b4ff853c09842b3b6bd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Wed, 21 May 2025 19:46:44 +0200 Subject: [PATCH 16/24] Update Exercise 1 based on review comments --- exercises/01_grundlagen_setup.adoc | 25 +++++-------------------- 1 file changed, 5 insertions(+), 20 deletions(-) diff --git a/exercises/01_grundlagen_setup.adoc b/exercises/01_grundlagen_setup.adoc index 13eef2d..5cf49eb 100644 --- a/exercises/01_grundlagen_setup.adoc +++ b/exercises/01_grundlagen_setup.adoc @@ -1,7 +1,6 @@ = Übung 1: Grundlagen-Setup und arc42-Template :toc: :icons: font -:source-highlighter: highlight.js == Was du lernst * docToolchain-Wrapper verwenden @@ -15,14 +14,14 @@ Du wirst lernen, wie du das arc42-Template herunterlädst und es mit docToolchai == Beispiel: docToolchain initialisieren -Der docToolchain-Wrapper `dtcw` ist bereits installiert. So kannst du verfügbare Aufgaben anzeigen: +Der docToolchain-Wrapper `dtcw` ist bereits installiert. So kannst du verfügbare Tasks anzeigen: [source,bash] ---- # docToolchain-Wrapper ausführbar machen chmod +x dtcw -# Verfügbare Aufgaben anzeigen +# Verfügbare Tasks anzeigen ./dtcw tasks --group doctoolchain ---- @@ -60,28 +59,14 @@ Ein Link zu einem anderen Abschnitt: <> * Bei der Frage nach Antora, wähle "n" (nein) 3. Generiere HTML aus dem Template: * `./dtcw generateHTML` -4. Öffne die generierte HTML-Datei aus dem build/docs/html5-Verzeichnis +4. Starte im Terminal einen einfachen HTTP-Server, um die HTML anzusehen: + * `python -m http.server 8000` + * Öffne dann im Browser: http://localhost:8000/build/docs/html5/ 5. Öffne die Datei `src/docs/arc42/index.adoc` und passe den Titel an: * Ändere den Titel zu einem aussagekräftigen Namen für dein Projekt * Passe auch die Autoren und andere Metadaten an 6. Generiere die HTML-Datei erneut und prüfe deine Änderung -== Automatisierung des downloadTemplate-Befehls - -Für CI/CD-Pipelines oder zur Automatisierung kannst du den `downloadTemplate`-Befehl mit vordefinierten Antworten ausführen: - -[source,bash] ----- -# Für Linux/macOS (Bash) -echo -e "1\nEN\nplain\nn" | ./dtcw downloadTemplate - -# Für Windows (Command Prompt) -(echo 1 & echo EN & echo plain & echo n) | .\dtcw.bat downloadTemplate - -# Für Windows (PowerShell) -"1`nEN`nplain`nn" | .\dtcw.ps1 downloadTemplate ----- - == Bonusaufgabe Generiere auch eine PDF-Version des Templates mit `./dtcw generatePDF` From c759f10a7505550c685c12f05dcdc078f960b0f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Wed, 21 May 2025 19:47:03 +0200 Subject: [PATCH 17/24] Update solution for Exercise 1 based on review comments --- solutions/01_grundlagen_setup_solution.adoc | 22 +++++++++------------ 1 file changed, 9 insertions(+), 13 deletions(-) diff --git a/solutions/01_grundlagen_setup_solution.adoc b/solutions/01_grundlagen_setup_solution.adoc index 50d0607..4fdbaac 100644 --- a/solutions/01_grundlagen_setup_solution.adoc +++ b/solutions/01_grundlagen_setup_solution.adoc @@ -1,7 +1,6 @@ = Lösung: Übung 1 - Grundlagen-Setup und arc42-Template :toc: :icons: font -:source-highlighter: highlight.js Diese Datei enthält eine Beispiellösung für die erste Übung. @@ -14,7 +13,7 @@ Zuerst machen wir den docToolchain-Wrapper ausführbar: chmod +x dtcw ---- -Dann prüfen wir, welche Aufgaben verfügbar sind: +Dann prüfen wir, welche Tasks verfügbar sind: [source,bash] ---- @@ -36,23 +35,25 @@ Bei den Abfragen wählen wir: * "plain" als Variante * "n" bei der Frage nach Antora -Alternativ können wir den Befehl auch automatisieren: +== Schritt 3: HTML generieren + +Wir generieren eine HTML-Version des Templates mit folgendem Befehl: [source,bash] ---- -echo -e "1\nEN\nplain\nn" | ./dtcw downloadTemplate +./dtcw generateHTML ---- -== Schritt 3: HTML generieren +Die generierte HTML-Datei finden wir unter `build/docs/html5/arc42/index.html`. -Wir generieren eine HTML-Version des Templates mit folgendem Befehl: +Zum Anzeigen der Datei starten wir einen lokalen HTTP-Server: [source,bash] ---- -./dtcw generateHTML +python -m http.server 8000 ---- -Die generierte HTML-Datei finden wir unter `build/docs/html5/arc42/index.html`. +Und öffnen dann im Browser: http://localhost:8000/build/docs/html5/ == Schritt 4: Dokumentation anpassen @@ -70,11 +71,6 @@ Wir öffnen die Datei `src/docs/arc42/index.adoc` und aktualisieren folgende Inh :toc-title: Table of Contents :experimental: :imagesdir: images -:tip-caption: 🚀 -:note-caption: ℹ️ -:important-caption: ⚠️ -:warning-caption: 🔥 -:caution-caption: 🔪 // additional style for arc42 help callouts ifdef::basebackend-html[] From 06b385e4cdc34d3fe5e7d0b51c1bb83a8981d745 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Wed, 21 May 2025 19:47:27 +0200 Subject: [PATCH 18/24] Update Exercise 2 to remove source-highlighter --- exercises/02_asciidoc_basics.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/exercises/02_asciidoc_basics.adoc b/exercises/02_asciidoc_basics.adoc index 7a68702..5572d60 100644 --- a/exercises/02_asciidoc_basics.adoc +++ b/exercises/02_asciidoc_basics.adoc @@ -1,7 +1,6 @@ = Übung 2: AsciiDoc-Basics mit arc42-Fokus :toc: :icons: font -:source-highlighter: highlight.js == Was du lernst * AsciiDoc-Syntax für Kapitelstruktur, Listen, Tabellen From b0a462c389c4df5a288a36dae0ad3141288b2466 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Wed, 21 May 2025 19:49:37 +0200 Subject: [PATCH 19/24] Update Exercise 3 to remove source-highlighter --- exercises/03_diagramme_plantuml_c4.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/exercises/03_diagramme_plantuml_c4.adoc b/exercises/03_diagramme_plantuml_c4.adoc index 10f6864..53ae898 100644 --- a/exercises/03_diagramme_plantuml_c4.adoc +++ b/exercises/03_diagramme_plantuml_c4.adoc @@ -1,7 +1,6 @@ = Übung 3: Diagramme mit PlantUML und C4 :toc: :icons: font -:source-highlighter: highlight.js == Was du lernst * PlantUML-Diagramme in arc42 integrieren From 9b34b60da27338f905f96ad203cb8ef88b40296c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Wed, 21 May 2025 19:50:11 +0200 Subject: [PATCH 20/24] Update Exercise 4 to remove source-highlighter --- exercises/04_architekturentscheidungen.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/exercises/04_architekturentscheidungen.adoc b/exercises/04_architekturentscheidungen.adoc index f4013f5..9a22df3 100644 --- a/exercises/04_architekturentscheidungen.adoc +++ b/exercises/04_architekturentscheidungen.adoc @@ -1,7 +1,6 @@ = Übung 4: Architekturentscheidungen dokumentieren :toc: :icons: font -:source-highlighter: highlight.js == Was du lernst * Architekturentscheidungen strukturiert dokumentieren From e3d4da63ff1f0196d8e5eac096c7c1b629f11f1a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Wed, 21 May 2025 19:50:49 +0200 Subject: [PATCH 21/24] Update Exercise 5 to remove source-highlighter --- exercises/05_qualitaetsziele_szenarien.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/exercises/05_qualitaetsziele_szenarien.adoc b/exercises/05_qualitaetsziele_szenarien.adoc index b17c0b0..2317b4e 100644 --- a/exercises/05_qualitaetsziele_szenarien.adoc +++ b/exercises/05_qualitaetsziele_szenarien.adoc @@ -1,7 +1,6 @@ = Übung 5: Qualitätsziele und Szenarien :toc: :icons: font -:source-highlighter: highlight.js == Was du lernst * Qualitätsbaum nach ISO 25010 erstellen From 4c17809fa700908c7c693c6bd8f1a8eca582c7da Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Wed, 21 May 2025 19:52:28 +0200 Subject: [PATCH 22/24] Update Exercise 6 to remove source-highlighter --- exercises/06_kollaboration_cicd.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/exercises/06_kollaboration_cicd.adoc b/exercises/06_kollaboration_cicd.adoc index b750e4c..ad16749 100644 --- a/exercises/06_kollaboration_cicd.adoc +++ b/exercises/06_kollaboration_cicd.adoc @@ -1,7 +1,6 @@ = Übung 6: Kollaboration und CI/CD-Integration :toc: :icons: font -:source-highlighter: highlight.js == Was du lernst * Dokumentation für Teamarbeit strukturieren From 8d6abc832b1f5baaa91ae7490879efd1f797b7c0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Wed, 21 May 2025 19:59:34 +0200 Subject: [PATCH 23/24] Update README.adoc with clearer GitHub Workspace instructions --- README.adoc | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/README.adoc b/README.adoc index d26dc3f..69e755b 100644 --- a/README.adoc +++ b/README.adoc @@ -8,7 +8,18 @@ Dieser Workshop führt dich in die Dokumentation von Software-Architektur mit As Die Übungen bauen aufeinander auf und vermitteln praktische Fähigkeiten für die Erstellung professioneller Architekturdokumentation. -Der Workshop findet in einem GitHub Workspace statt. Damit wird ein VS Code im Browser geöffnet, und du erhältst sofort Zugriff auf einen Editor mit AsciiDoc-Preview-Funktion. +== Workshop starten mit GitHub Workspace + +**Um diesen Workshop zu starten, öffne dieses Repository in einem GitHub Workspace:** + +1. Stelle sicher, dass du in GitHub eingeloggt bist +2. Drücke auf `.` (Punkt) während du im Repository bist, oder ergänze `.dev` in der URL + (z.B. `https://github.com/rdmueller/empty-workshop.git` -> `https://github.dev/rdmueller/empty-workshop.git`) +3. GitHub startet einen Visual Studio Code Editor direkt im Browser +4. Dieser Editor bietet vollständige Funktionalität, einschließlich AsciiDoc-Preview +5. Um die AsciiDoc-Vorschau zu aktivieren, drücke `Ctrl+K` gefolgt von `V` (oder `Cmd+K, V` auf Mac) + +Alle benötigten Tools wie docToolchain sind bereits vorinstalliert und einsatzbereit. == Voraussetzungen From a05dde0f5c09f6ff839cb5b6ad29bb9e2b5b1ae6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Wed, 21 May 2025 19:59:53 +0200 Subject: [PATCH 24/24] Update solution file to remove additional styles for arc42 help callouts --- solutions/01_grundlagen_setup_solution.adoc | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/solutions/01_grundlagen_setup_solution.adoc b/solutions/01_grundlagen_setup_solution.adoc index 4fdbaac..a5fab0b 100644 --- a/solutions/01_grundlagen_setup_solution.adoc +++ b/solutions/01_grundlagen_setup_solution.adoc @@ -72,22 +72,6 @@ Wir öffnen die Datei `src/docs/arc42/index.adoc` und aktualisieren folgende Inh :experimental: :imagesdir: images -// additional style for arc42 help callouts -ifdef::basebackend-html[] -++++ - -++++ -endif::basebackend-html[] - // horizontal line ***