1. Vorbereitung
Installiere docToolchain und Lade das aktuelle arc42 Template.
| Im README.adoc steht, wie es geht. |
Lösung
curl -Lo dtcw doctoolchain.github.io/dtcw
chmod +x dtcw
./dtcw docker downloadTemplatesiehe auch install docToolchain, arc42.org
2. Qualitätsziele
Erstelle einen Qualitätsbaum und baue ihn in Kapitel 10 ein.
Unter src/docs/images/quality-tree.puml liegt schon ein vollständiger ISO/IEC 25010 Qualitätsbaum.
Lösung
Kapitel 10 liegt unter src/docs/arc42/chapters/10_quality_requirements.adoc
Den Qulitätsbaum referenzierst Du als PlantUML über
[plantuml, quality-tree]
....
include::../../images/quality-tree.puml[]
....|
PlantUML und andere Diagramme können gut über einen Kroki.io Server gerendert werden. Der Server wird in AsciiDoc wie folgt konfiguriert: |
siehe auch AsciiDoc Diagram-Extension, AsciiDoc Include-Directive
Der Baum nimmt viel Platz ein wird dadurch klein und unleserlich dargestellt.
Konzentriere Dich auf den Security-Aspekt und stelle in einem weiteren Absatz Security nur den Security-Zweig des Baums dar.
| Schau Dir den Source nochmal genau an. Du musst den Include nur leicht erweitern. |
Lösung
==== Security
[plantuml, sec-quality-tree]
....
include::../../images/quality-tree.puml[tags=base;sicherheit]
....
achte darauf den Namen sec-quality-tree für jedes Diagramm zu überschreiben, da sonst nur ein Diagramm erzeugt wird (die erzeugten Diagramme überschreiben sich sonst)
|
siehe auch AsciiDoc tagged-regions
3. Systemkontext
Nutze draw.io um einen Systemkontext zu zeichnen. Binde den Systemkontext in Kapitel 3 ein.
| das draw.io Plugin ist in der gitpod Umgebung schon vorinstalliert. |
Lösung
Lege unter src/docs/images/C4/systemkontext.dio.svg eine leere Datei an.
Diese öffnet sich selbst sofort im draw.io-Plugin.
Skizziere den Systemkontext.
Öffne die AsciiDoc-Datei für Kapitel 3 und referenziere den Systemkontext via
image::C4/systemkontext.dio.svg[]Verfeinere den Systemkontext weiter.
4. ADRs: Pugh-Matrix
Erstelle eine Pugh-Matrix in Excel als graphische Übersicht der bewerteten Qualitätskriterien verschiedener Optionen einer Entscheidung.
Binde die Pugh-Matrix in einen ADR in Kapitel 9 ein.
Lösung
Ein Beispiel einer Pugh-Matrix in Excel findest Du unter src/docs/Pugh-Matrix-Decision.xlsx.
Du kannst sie editieren und Deinen Wünschen anpassen.
Mit dem Kommando
./dtcw docker exportExcel
exportierst Du alle Excel-Files im Projekt nach CSV und AsciiDoc.
Du findest die Files unter src/docs/excel/[name des Excel-Files]/[Name des Worksheets].adoc.
Siehe auch exportExcel
Was fällt Dir auf?
Lösung
Es werden nicht nur die Daten aus dem Excel-File exportiert, sondern auch Farben, Col- und Row-Spans und Formeln werden berechnet.
5. Skizzieren mit MS PowerPoint
Als Architekt bist Du es wahrscheinlich gewöhnt Deine Architektur mit PowerPoint zu skizzieren und präsentieren.
Erstelle eine Lösungsskizze / Big Picture / Informelle Übersicht mit PowerPoint und binde 1-2 Slides in Deine Dokumentation ein.
Verwende {slide} in den Speakernotes um den Dateinamen der exportierten Folie zu erhalten.
|
| der hierfür notwendige Task funktioniert momentan nur unter Windows, da er PowerPoint per VisualBasic-Script fernstuert. Unter anderen Betriebssystemen können entsprechende Sichten z.B. mit draw.io (nächster Abschnitt) erstellt werden. |
Lösung
Powerpoint lässt sich ähnlich wie Excel in Deine Dokumentation einbauen.
Verwende dazu den Task exportPPT.
Dabei werden die Folien einzeln als .jpg und alle Speakernotes zusammen als .ad (AsciiDoc) exportiert.
Da die Namen der exportierten Slides nicht ganz einfach zu erkennen sind, kann in den Speakernotes {slide} als Platzhalter verwendet werden, der automatisch ersetzt wird.
Durch das gezielte setzen von // tag::[] können leicht einzelne Slides und deren beschreibender Text in AsciiDoc inkludiert werden.
siehe auch exportPPT
| PowerPoint kann mit einem Stift auch sehr gut als digitales Whiteboard eingesetzt werden. |
6. Skizzieren mit draw.io
Auch draw.io eigent sich hervorragend für Skizzen.
Skizziere diesmal eine Änderung an einem Frontend, indem Du einen Screenshot des Frontends in draw.io mit Anmerkungen versiehst.
Lösung
Die Heransgehensweise sollte klar sein. Das insteressante daran ist, dass Du per Copy & Paste einen Screenshot in draw.io kopieren kannst und diesen dann mit Vektorgrafiken annotieren kannst.
Draw.io speichert bei den Formaten .png und .svg den Source in den Meta-Daten.
Dadurch kann solch ein annotierter Screenshot jederzeit erneut geöffnet und verändert werden.
7. Laufzeitsicht
Erstelle mit PlantUML eine Laufzeitsicht in Form eines Sequenzdiagramms, die das Zusammenspiel der Systeme darstellt. Referenziere das Ergebnis aus Kapitel 6.
Lösung
Sequenzdiagramme sind für PlantUML ein Kinderspiel, da das Layout direkt von der Diagrammdefinition vorgegeben ist.
Ist nichts vorgegeben, so ist ein PlantUML Diagramm automatisch ein Sequenzdiagramm. Somit müssen eigentlich nur noch die Verbindungen definiert werden.
[plantuml, sequenz-demo]
....
User -> Browser
Browser -> Server
Server -> Database
Server <-- Database
Browser <-- Server
User <-- Browser
....siehe auch Plantuml: Sequenzdiagramm
8. Bausteinsicht
Die Bausteinsicht ist durch ihre Hirarchie etwas herausfordernd. Hier gibt es mehrere Ansätze.
8.1. Bausteinsicht mit draw.io
Öffne den Systemkontext in draw.io und füge den Elementen in draw.io Links auf Unterseiten hinzu.
Binde die Grafik so ein, dass die Links funktionieren.
das funktioniert nur bei .svg-Grafiken, die inline eingebunden werden.
|
Lösung
Das Diagramm muss mit opts=inline eingebunden werden.
Das führt aber zu Problemen mit dem imagesdir, welches der generierten HTML Seite sagt, wo die Bilder liegen.
Durch die inline Option muss Asciidoctor allerdins schon beim Rendering die Datei einbinden.
Folgendes Fragment funktioniert:
:currentImagesDir: {imagesDir}
// je nach Folder muss hier der Verweis richtig gesetzt werden
:imagesdir: ../../../images/
image::C4/systemkontext.dio.svg[opts=inline]
:imagesDir: {currentImagesDir}
Dieses Beispiel kann weitergeführt werden, indem die hirarchische Struktur der Bausteinsicht in den Dokumenten und im images-Verzeichnis nachgebaut und verlinkt wird
|
8.2. Bausteinsicht mit PlantUML
Auch PlantUML unterstützt Links in .svg Diagrammen.
Hier besteht der Vorteil, dass kein imagesdir manipuliert werden muss.
Die Diagramme werden mit zwei identischen Optionen für unterschiedliche Ausgaben eingebunden:
Lösung plain PlantUML
[plantuml,demo1,svg,opts="inline",svg-type="inline"]
-----
@startuml
set separator none
title Software System - System Context
top to bottom direction
skinparam {
arrowFontSize 10
defaultTextAlignment center
wrapWidth 200
maxMessageSize 100
}
hide stereotype
skinparam rectangle<<SoftwareSystem>> {
BackgroundColor #1168bd
FontColor #ffffff
BorderColor #0b4884
shadowing false
HyperlinkColor #ffffff
}
skinparam person<<User>> {
BackgroundColor #08427b
FontColor #ffffff
BorderColor #052e56
shadowing false
}
person "==User\n<size:10>[Person]</size>\n\nA user of my software system." <<User>> as User
rectangle "==Software System\n<size:10>[Software System]</size>\n\nMy software system." <<SoftwareSystem>> as SoftwareSystem [[01_BigSpender/01_container.html]]
User .[#707070,thickness=2].> SoftwareSystem : "<color:#707070>Uses"
@enduml
-----Lösung C4 Plantuml
[plantuml,demo2,svg,opts="inline",svg-type="inline"]
-----
@startuml
set separator none
title Software System - System Context
skinparam {
HyperlinkColor #ffffff
}
top to bottom direction
!include <C4/C4>
!include <C4/C4_Context>
Person(User, "User", $descr="A user of my software system.", $tags="", $link="")
System(SoftwareSystem, "Software System", $descr="My software system.", $tags="", $link="01_BigSpender/01_container.html")
Rel(User, SoftwareSystem, "Uses", $techn="", $tags="", $link="")
SHOW_LEGEND(true)
@enduml
-----8.3. Bausteinsicht mit Structurizr
Du kannst auch Structurizr von Simon Brown zum Erstellen von C4 Diagrammen verwenden.
Schlage im README.adoc nach, wie Du Structurizr-Lite starten kannst um eine workspace.dsl zu verwenden.