forked from docToolchain/empty-workshop
-
Notifications
You must be signed in to change notification settings - Fork 0
Add AsciiDoc workshop exercises for software architecture #1
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
raifdmueller
wants to merge
24
commits into
docToolchain-ready
Choose a base branch
from
issue-6-workshop-exercises
base: docToolchain-ready
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
24 commits
Select commit
Hold shift + click to select a range
9d57972
Update README.adoc with workshop structure
raifdmueller ce10131
Create exercises directory with README
raifdmueller 5b13406
Create solutions directory with README
raifdmueller 107381a
Add references.adoc with useful links
raifdmueller c798de5
Add project-ideas.adoc with sample projects
raifdmueller 403cda3
Add Exercise 1: Basic Setup and arc42 Template
raifdmueller 11af7e3
Add Exercise 2: AsciiDoc Basics with arc42 Focus
raifdmueller 10f48e8
Add Exercise 3: Diagrams with PlantUML and C4
raifdmueller 09936b4
Add Exercise 4: Documenting Architecture Decisions
raifdmueller ec6349a
Add Exercise 5: Quality Goals and Scenarios
raifdmueller 8b2cd28
Add Exercise 6: Collaboration and CI/CD Integration
raifdmueller 091da59
Add solution example for Exercise 1
raifdmueller 1b7dba6
Update README.adoc based on review comments
raifdmueller 5f82b70
Update project-ideas.adoc based on review comments
raifdmueller 791672d
Update references.adoc based on review comments
raifdmueller fa4216e
Update Exercise 1 based on review comments
raifdmueller c759f10
Update solution for Exercise 1 based on review comments
raifdmueller 06b385e
Update Exercise 2 to remove source-highlighter
raifdmueller b0a462c
Update Exercise 3 to remove source-highlighter
raifdmueller 9b34b60
Update Exercise 4 to remove source-highlighter
raifdmueller e3d4da6
Update Exercise 5 to remove source-highlighter
raifdmueller 4c17809
Update Exercise 6 to remove source-highlighter
raifdmueller 8d6abc8
Update README.adoc with clearer GitHub Workspace instructions
raifdmueller a05dde0
Update solution file to remove additional styles for arc42 help callouts
raifdmueller File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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: <<Erster 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` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 <<stakeholder>> 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 <<section-id>> 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` |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.