diff --git a/README.adoc b/README.adoc index 99aa570..69e755b 100644 --- a/README.adoc +++ b/README.adoc @@ -1,33 +1,71 @@ -== Empty Repository += AsciiDoc für Software-Architektur Workshop +:toc: +:icons: font -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. +== Workshop starten mit GitHub Workspace -Now open xref:src/docs/diagrams-as-code.adoc[] and start hacking. +**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) -=== advanced +Alle benötigten Tools wie docToolchain sind bereits vorinstalliert und einsatzbereit. -To install _docToolchain_, switch to the terminal and run +== Voraussetzungen -[code, bash] +* Grundlegende Kenntnisse in der Softwareentwicklung +* Git-Grundlagen +* Ein Texteditor mit AsciiDoc-Unterstützung (VSCode mit AsciiDoc-Plugin empfohlen) + +== Workshop-Struktur + +Der Workshop ist in sechs Übungen gegliedert: + +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 + +Alle Übungen befinden sich im Ordner `exercises/`. Lösungsbeispiele findest du im Ordner `solutions/`. + +== Erste Schritte + +1. Stelle sicher, dass docToolchain funktioniert (es ist bereits vorinstalliert): ++ +[source,bash] ---- -curl -Lo dtcw doctoolchain.github.io/dtcw -chmod +x dtcw -./dtcw install +# Zeige verfügbare Tasks an +./dtcw tasks --group doctoolchain ---- -To preview the files, start a small server from within the terminal: - -[code, bash] +2. Öffne die erste Übung: ++ +[source] ---- -python -m http.server 8000 +exercises/01_grundlagen_setup.adoc ---- -Gitpod will now ask you what to do with the opened port. Just click on "open in browser" and navigate through the `build` folder. +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 + +== Ü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 diff --git a/exercises/01_grundlagen_setup.adoc b/exercises/01_grundlagen_setup.adoc new file mode 100644 index 0000000..5cf49eb --- /dev/null +++ b/exercises/01_grundlagen_setup.adoc @@ -0,0 +1,80 @@ += Übung 1: Grundlagen-Setup und arc42-Template +:toc: +:icons: font + +== 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 Tasks anzeigen: + +[source,bash] +---- +# docToolchain-Wrapper ausführbar machen +chmod +x dtcw + +# Verfügbare Tasks 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. 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 + +== 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` diff --git a/exercises/02_asciidoc_basics.adoc b/exercises/02_asciidoc_basics.adoc new file mode 100644 index 0000000..5572d60 --- /dev/null +++ b/exercises/02_asciidoc_basics.adoc @@ -0,0 +1,135 @@ += Übung 2: AsciiDoc-Basics mit arc42-Fokus +:toc: +:icons: font + +== 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` diff --git a/exercises/03_diagramme_plantuml_c4.adoc b/exercises/03_diagramme_plantuml_c4.adoc new file mode 100644 index 0000000..53ae898 --- /dev/null +++ b/exercises/03_diagramme_plantuml_c4.adoc @@ -0,0 +1,158 @@ += Übung 3: Diagramme mit PlantUML und C4 +:toc: +:icons: font + +== 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` diff --git a/exercises/04_architekturentscheidungen.adoc b/exercises/04_architekturentscheidungen.adoc new file mode 100644 index 0000000..9a22df3 --- /dev/null +++ b/exercises/04_architekturentscheidungen.adoc @@ -0,0 +1,131 @@ += Übung 4: Architekturentscheidungen dokumentieren +:toc: +:icons: font + +== 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` diff --git a/exercises/05_qualitaetsziele_szenarien.adoc b/exercises/05_qualitaetsziele_szenarien.adoc new file mode 100644 index 0000000..2317b4e --- /dev/null +++ b/exercises/05_qualitaetsziele_szenarien.adoc @@ -0,0 +1,161 @@ += Übung 5: Qualitätsziele und Szenarien +:toc: +:icons: font + +== 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` diff --git a/exercises/06_kollaboration_cicd.adoc b/exercises/06_kollaboration_cicd.adoc new file mode 100644 index 0000000..ad16749 --- /dev/null +++ b/exercises/06_kollaboration_cicd.adoc @@ -0,0 +1,237 @@ += Übung 6: Kollaboration und CI/CD-Integration +:toc: +:icons: font + +== 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! 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 diff --git a/project-ideas.adoc b/project-ideas.adoc new file mode 100644 index 0000000..f8c3c2d --- /dev/null +++ b/project-ideas.adoc @@ -0,0 +1,130 @@ += Projektideen +:toc: +:icons: font + +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. + +.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 diff --git a/references.adoc b/references.adoc new file mode 100644 index 0000000..d2a14a6 --- /dev/null +++ b/references.adoc @@ -0,0 +1,46 @@ += 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://asciidoctor.org/docs/asciidoctor-pdf/[PDF-Erzeugung mit Asciidoctor] +* https://github.com/asciidoctor/asciidoctor-diagram[Asciidoctor Diagram Integration] diff --git a/solutions/01_grundlagen_setup_solution.adoc b/solutions/01_grundlagen_setup_solution.adoc new file mode 100644 index 0000000..a5fab0b --- /dev/null +++ b/solutions/01_grundlagen_setup_solution.adoc @@ -0,0 +1,121 @@ += Lösung: Übung 1 - Grundlagen-Setup und arc42-Template +:toc: +:icons: font + +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 Tasks 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 + +== 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`. + +Zum Anzeigen der Datei starten wir einen lokalen HTTP-Server: + +[source,bash] +---- +python -m http.server 8000 +---- + +Und öffnen dann im Browser: http://localhost:8000/build/docs/html5/ + +== 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 + +// 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 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