WJAX 2015: arc42 Reality Check

Seit über 10 Jahren gibt es arc42 - die pragmatische Vorlage/Arbeitshilfe für
Architekturdokumentation. Im Vortrag stelle ich diverse Optionen für den Praxiseinsatz
von arc42 vor - von Werkzeugen bis hin zur Organisation von Dokumentation im Projekt.

Anhand von Beispielen zeige ich auf, wie Architektur- und Codedokumentation
zusammenspielt - und wie wir eine pragmatische und nützliche
(technische) Projektdokumentation aufsetzen können.

Insbesondere sehen Sie textbasierte (AsciiDoc)-Dokumentation im Zusammenspiel
mit Modellierungswerkzeugen wie Enterprise-Architect (tm) und VisualParadigm (tm)
im Einsatz - und wie das zusammen mit git auch entwicklerfreundlich funktioniert.

Transcript

1. Reality Check Praxiseinsatz, Werkzeuge, Add-Ons Dr. Gernot Starke innoQ Fellow WJAX, November 2015
2. Dr. Gernot Starke innoQ Fellow   Softwarearchitekturen Entwurf, Entwicklung, Management Evolution & Modernisierung Dokumentation Training   Mentoring und Coaching Analyse und Optimierung von Entwicklungsprozessen   Reviews +49 177 – 728 2570 Gernot.Starke@innoQ.com www.arc42.de
3. Was ist arc42?
4. Behälter für Architektur-Info Anforderungen Entscheidungen Strukturen von Sourcecode
5. Warum?
6. hQp://www.flickr.com/photos/mistressf/737350025/sizes/l/
10. Wie sieht‘s aus?
11. AuYau
13. AuYau von arc42, Version 6, Stand März 2012. © Dr. Peter Hruschka und Dr. Gernot Starke. Frei für kommerzielle und private Nutzung. 1. Einführung und Ziele 1.1 Aufgabenstellung 1.2 Qualitätsziele 1.3 Stakeholder 7.Verteilungssicht 7.1 Infrastruktur Ebene 1 7.2 Infrastruktur Ebene 2 …. 2. Randbedingungen 2.1 Technische Randbedingungen 2.2 Organisatorische Randbedingungen 2.3 Konventionen 3. Kontextabgrenzung 3.1 Fachlicher Kontext 3.2 Technischer- oder Verteilungskontext 4. Lösungsstrategie 5. Bausteinsicht 5.1 Ebene 1 5.2 Ebene 2 …. 6. Laufzeitsicht 6.1 Laufzeitszenario 1 6.2 Laufzeitszenario 2 …. 8. Konzepte 8.1 Fachliche Struktur und Modelle 8.2 Typische Muster und Strukturen 8.3 Persistenz 8.4 Benutzeroberfläche …. 9. Entwurfsentscheidungen 9.1 Entwurfsentscheidung 1 9.2 Entwurfsentscheidung 2 …. 10. Qualitätsszenarien 10.1 Qualitätsbaum 10.2 Qualitäts-/Bewertungsszenarien 11. Risiken 12. Glossar
14. 2006... delta
15. Beispiel (Datenmigra\on, 4000+ PT)
16. Beispiel (CRM-System, 2000+ PT)
17. Beispiel „htmlSanityCheck“ hQps://github.com/aim42/htmlsanitycheck
18. Beispiel „htmlSanityCheck“ (2)
19. Mit arc42 starten?
20. Mit arc42 starten (Tag 1) Beispiele! Pragmatische Hilfe für Softwarearchitekten gernot STARKE peter HRUSCHKA hQp://aim42.github.io/htmlSanityCheck/
21. -Stand Pragmatische Hilfe für Softwarearchitekten gernot STARKE peter HRUSCHKA * gerne im Tausch gegen vcard *
22. Mit arc42 starten (Tag 1)
23. Mit arc42 starten (Tag 1) Idee + Ausführung: Stefan Zörner (hQp://embarc.de)
24. Mit arc42 starten (Tag 1) Mehr Beispiele! hQp://confluence.arc42.org: •  CRM-System (2000+ PT) •  Datenmigra\on (4000+ PT)
25. Mit arc42 starten (Tag 1, 13:30h)... neue Systeme 1.  Kontext 2.  Qualitätsziele 3.  Lösungsstrategie 4.  Konzepte 1.  Domäne 2.  Persistenz, UI etc. bestehende Systeme 1.  Bausteine (Code-Struktur) Level 1 2.  Konzepte + typische Lösungsmuster 3.  Externe SchniQstellen (= Kontext)
26. Mit arc42 im Projekt?
27. Mit arc42 im Projekt... Projektdokumenta\on Systemdokumenta\on Team „Gärtner“
28. Mit arc42 im Projekt... Projektdokumenta\on ~arc42 „locker“ Diskussionen Implementa\on-Guide, Tasks / Issues Systemdokumenta\on Weitere relevante Infos... (Betrieb/Admin, Test, Release...) 11. Risiken ARC42 Architektur-Dokumentation 1. Einführung und Ziele 2. Randbedingungen 3. Kontextabgrenzung 5. Bausteinsicht 6. Laufzeitsicht 7. Verteilungssicht 8. Konzepte 10. Qualitätsszenarien 9. Entwurfsentscheidungen 4. Lösungsstrategie 12. Glossar Team „Gärtner“
29. Große Systeme mit arc42?
30. arc42 und größere Systeme Gesamtsystem Kontextabgrenzung (externe SchniQstellen) Bausteinsicht L1 Ablauf System-UseCases Zentrale Entscheidungen Zentrale Konzepte Subsystem #1 Bausteinsicht Lokale Abläufe Subsystem #2 Bausteinsicht Lokale Abläufe Subsystem #3 Bausteinsicht Lokale Abläufe 11. Risiken ARC42 Architektur-Dokumentation 1. Einführung und Ziele 2. Randbedingungen 3. Kontextabgrenzung 5. Bausteinsicht 6. Laufzeitsicht 7. Verteilungssicht 8. Konzepte 10. Qualitätsszenarien 9. Entwurfsentscheidungen 4. Lösungsstrategie 12. Glossar 11. Risiken ARC42 Architektur-Dokumentation 1. Einführung und Ziele 2. Randbedingungen 3. Kontextabgrenzung 5. Bausteinsicht 6. Laufzeitsicht 7. Verteilungssicht 8. Konzepte 10. Qualitätsszenarien 9. Entwurfsentscheidungen 4. Lösungsstrategie 12. Glossar 11. Risiken ARC42 Architektur-Dokumentation 1. Einführung und Ziele 2. Randbedingungen 3. Kontextabgrenzung 5. Bausteinsicht 6. Laufzeitsicht 7. Verteilungssicht 8. Konzepte 10. Qualitätsszenarien 9. Entwurfsentscheidungen 4. Lösungsstrategie 12. Glossar 11. Risiken ARC42 Architektur-Dokumentation 1. Einführung und Ziele 2. Randbedingungen 3. Kontextabgrenzung 5. Bausteinsicht 6. Laufzeitsicht 7. Verteilungssicht 8. Konzepte 10. Qualitätsszenarien 9. Entwurfsentscheidungen 4. Lösungsstrategie 12. Glossar Link Link Link
31. Kleine Systeme mit arc42?
32. Kleine Systeme... Leeres Template == 26 Seiten Übertrieben für kleine Projekte, oder?
33. Kleine Systeme... Leeres Template == 26 Seiten Übertrieben für kleine Projekte, oder? arc42 == Schrank, nicht Formular SUPER für kleine Projekte: •  !meboxed verwenden •  essen\elle Dinge einbringen
34. Beispiel „kleines System“
35. Code und Bausteinsicht?
36. Building Blocks Hierarchy Kontext Level 1 Level 2 Level 3 H t ml S a n it y Check use r Bu ild sy st em (e.g . G r adle, m ake) loc al ht ml file(s) loc al i m ages exter n al websites & resources * Risk * references « p ost po n ed » checks checks checks references H t ml S a n it y Check loc al - ht ml loc al -i m ages user build - syste m exter n al websites local - resources HS C Co re AllChecksRun ner local file syste m Results ht t p (exter n al) HS C G r a d le Plu gin HSC Com m a n d Lin e In t erfa ce HS C G r a phic al In t erfac e done pla n n ed L egend via shell HS C Co re AllChecksRun ner local file syste m Results ht t p (exter n al) «li br a r y » H t ml P a rser Results Collect o r Fin d in g s A ll Checks R un n e r done pla n n ed L egend Ch ecker Su ggest er Re po r t e r fin d suggestions crea te / execu te 1.. a d d Fin d in g pa rse Results Results Collect o r Results Re po r t e r Pe r - Ru n Results Sin gle C heck Resu lts w h a tIsC heck ed : St rin g sourceIte m :St ring t a r getIt em :St ri n g n r OfIte msChecked :in t Sin gle P age Resu lts pageN a m e :St ring pa geTit le :S t rin g m et aInfo :PageMet aInfo Fin d in g it e m :S t rin g sug gest ion :St rin g Fin d in g s a d d - Fin d in g 1.. * 0.. * 1 unused i m ages 1 Gradle sub-projects: •  core: org.aim42.htmlsanitycheck •  gradle-plugin: org.aim42.htmlsanitycheck
37. Building Blocks Hierarchy Kontext Level 1 Level 2 Level 3 H t ml S a n it y Check use r Bu ild sy st em (e.g . G r adle, m ake) loc al ht ml file(s) loc al i m ages exter n al websites & resources * Risk * references « p ost po n ed » checks checks checks references H t ml S a n it y Check loc al - ht ml loc al -i m ages user build - syste m exter n al websites local - resources HS C Co re AllChecksRun ner local file syste m Results ht t p (exter n al) HS C G r a d le Plu gin HSC Com m a n d Lin e In t erfa ce HS C G r a phic al In t erfac e done pla n n ed L egend via shell HS C Co re AllChecksRun ner local file syste m Results ht t p (exter n al) «li br a r y » H t ml P a rser Results Collect o r Fin d in g s A ll Checks R un n e r done pla n n ed L egend Ch ecker Su ggest er Re po r t e r fin d suggestions crea te / execu te 1.. a d d Fin d in g pa rse Results Results Collect o r Results Re po r t e r Pe r - Ru n Results Sin gle C heck Resu lts w h a tIsC heck ed : St rin g sourceIte m :St ring t a r getIt em :St ri n g n r OfIte msChecked :in t Sin gle P age Resu lts pageN a m e :St ring pa geTit le :S t rin g m et aInfo :PageMet aInfo Fin d in g it e m :S t rin g sug gest ion :St rin g Fin d in g s a d d - Fin d in g 1.. * 0.. * 1 unused i m ages 1 Gradle sub-projects: •  core: org.aim42.htmlsanitycheck •  gradle-plugin: org.aim42.htmlsanitycheck Classes: AllChecksRunner MissingConfigException Packages: o.a.h.check o.a.h.collect o.a.h.html o.a.h.report Classes: Checker.groovy ImageMapChecker MissingImageFilesChecker
38. Level-1: Codestruktur im Großen
39. Code in der Dokumenta\on?
40. Code in Doku: Beispiel... Wich\g: NCP (never copy-paste)
41. Code in Doku: Beispiel... [source, groovy] .Interface RunResults ---- include::{coresourcepath}/htmlsanitycheck/collect/ RunResults.groovy[tags=RunResultInterface] ---- asciidoc-Source
42. Konzepte!
43. Was ist ein Konzept? Beispiele im Bauwesen: •  Fenster und –griffe •  Heizung / Klima •  Flach-/Walm-/Spitzdach
44. Was ist ein Konzept? Beispiele: ‣  Persistenz ‣  Repor\ng ‣  Batch ‣  Validierung ‣  .... Plan zur Lösung von •  mehrfach auuretenden, •  übergreifenden Problemen.
45. Themen finden Gliederung nach S. Zörner ‣  Architekturmuster ‣  Entwicklung / Weiterentwicklung –  Codegenerierung, Buildmanagment, Tests, Migra\on, Konfigura\on, Modellierung ‣  Unter-der-Haube –  Persistenz, Verteilung, Sicherheit, Transak\onen, Sessions, Caching, Parallelisierung, Threading, Geschäusregeln, Batchverarbeitung ‣  Interak\on –  UI, i18n, Ergonomie, Validierung, Barrierefreiheit, Plausibilisierung, Ausnahme-/Fehlerbehandlung, Ablaufsteuerung, Kommunika\on, Integra\on, Repor\ng ‣  Betrieb ---------------- ----------- --------------- -------------------- ---------- ----------------- ------- -------------- --------------------- Iden\fizieren ----------- ---------- ----------------------- ----- Priorisieren --------------- -------------------------- ------------------------------ -------------- ---------- ------------------------------ -------------------- --------------------------- ------------------------- ----------------------------- ausführen
46. Konzepte anwenden... Bausteinsicht: -  Zeigt Stereotypen (=> Verweise auf Konzepte) Konzepte: –  erklären Implemen\erung, mit Beispielen someWhitebox «Entity» Customer «Web-UI» Planning «REST» Foo-IF «RelationalDB» MySQL «Batch» Adress- validierung «Report» Sales FooApp «Entity» Competition
47. Werkzeuge!
48. Anforderungen an Tools •  Text + Tabellen •  Diagramme •  Verweise •  Mul\-User •  Änderungshistorie •  Versioniert
49. Variante 1: plain-Wiki •  Text + Tabellen •  Diagramme •  Verweise •  Mul\-User •  Änderungshistorie •  Versioniert
50. Variante 1b: plain-Wiki++ •  Text + Tabellen •  Diagramme •  Verweise •  Mul\-User •  Änderungshistorie •  Versioniert Zeichen-Tool (Visio, Graffle & Co)
51. Variante 1c: Wiki + Grafik-Plugin •  Text + Tabellen •  Diagramme •  Verweise •  Mul\-User •  Änderungshistorie •  Versioniert Etwa: Gliffy (für Confluence)
52. Variante 2: Wiki + UML-Tool •  Text + Tabellen •  Diagramme •  Verweise •  Mul\-User •  Änderungshistorie •  Versioniert UML-Tool (Enterprise-Architect, MagicDraw, Visual-Paradigm & Co) •  Usability •  Akzeptanz
53. Variante 2: Plaintext + UML-Tool •  Text + Tabellen •  Diagramme •  Verweise •  Mul\-User •  Änderungshistorie •  Versioniert AsciiDoc, Markdown •  Geek-Faktor
54. AsciiDoc... •  Plaintext (git, diff) •  Build z.B. mit Gradle •  Zielformate: html, epub, pdf
55. Confluence + ProjectDoc (kommerziell) •  Idee: flüssigeres Arbeiten dank Wizards hQps://www.smar\cs.de/go/arc42
56. arc42 mit projectdoc-Blueprints •  Vorlagen als Schreibhilfen
57. HTML Sanity Checker mit projectdoc
58. Variante 3: UML-Tool •  Text + Tabellen •  Diagramme •  Verweise •  Mul\-User •  Änderungshistorie •  Versioniert Enterprise-Architect, Visual Paradigm etc. •  Geek-Faktor Modelle
59. Beispiel: arc42 mit EA
60. UML-Tool + Export-Automa\sierung •  Export aus Enterprise-Architect™ – Skript in github.com/arc42 vorhanden •  Export aus VisualParadigm™ – Export möglich •  bislang kein OpenSource Skript verfügbar
61. Wohin damit?
62. Wohin mit Domain-Model? 1.  (gut) QuerschniQliche Konzepte 2.  (ok) Bausteinsicht („Domain-Component“) 3.  (hhm) Eigenes (neues) Kapitel
63. Wohin mit UI/Layout, Masken oder Screenflow? 1.  QuerschniQliche Konzepte 2.  Eigene Sicht •  (== neues Kapitel)
64. Kata mit arc42 („Hands-on Workshop“)
65. Ziele einer Architektur-Kata •  Gemeinsames Verständnis •  Aufgaben „erproben“ •  Aspekte von „Architektur“ erarbeiten
66. Kata mit arc42 Aufgabe Anforderungen Qualitätsziele Kontext Lösungsidee Bausteine Konzepte
67. Subprojekte! Qualitätsanforderungen wesentliche Architekturaufgaben
68. Beispiele für Q-Anforderungen •  Q-Szenarien – Etwa 60 praxisnahe Qualitätsziele (aus konkreten Projekten/Systemen abstrahiert) •  Defini\onen für typische Q-Anforderungen – 70+ häufig vorkommende Begriffe rund um Qualität – pragma\sch definiert
69. Beispiele für Q-Anforderungen
70. Architektur- Aufgaben... hQps://github.com/arc42/arc-process Architektur bewerten Anforderungen und Randbedingungen klären Technische Konzepte entwerfen Umsetzung begleiten Architektur kommunizieren Strukturen entwerfen
71. Dr. Gernot Starke Gernot.Starke@innoQ.com hQp://arc42.de hQp://innoq.com hQps://www.flickr.com/photos/foto_db/16000636092