Architekturdokumentation in der Praxis

Über den (armseligen) Zustand der Dokumentation von Softwarearchitekturen in der Praxis - und was Sie mit einfachen, pragmatischen Mitteln dagegen tun können.

(Vorlesung an der FH Rhein Sieg vom April 2013)

Transcript

1. Architekturdokumentation in der Praxis Dr. Gernot Starke
2. Dr. Gernot Starke performant flexibel integriert geboren in Prograland, lebt in Architektonien, Visa für Analytistan und LaTesta, lange Aufenthalte in Bisi-Ness, Schwimmabzeichen im Service-Ozean aktiv
3. aktiv Fellow
4. member of: (co) founder of: enjoying: Fellow
7. Doku-Beispiel (0) http://www.flickr.com/photos/mistressf/737350025/sizes/l/
9. Doku-Beispiel (1)
11. Doku-Beispiel (2) http://www.flickr.com/photos/nohair_/4563162860/sizes/o/
12. Doku-Beispiel (3)....
14. Angemessene (gute) Architekturdokumentation in der Praxis Dr. Gernot Starke Neuer Titel:
15. Gute Arc-Doku ist... korrekt verständlich wartbar aktuell leicht zu lesen und zu schreiben! (angemessen) kurz
16. These: Es gibt Systeme mit guter Architekturdokumentation
17. These: Es gibt Systeme mit guter Architekturdokumentation aber nur wenige!
18. Grady Booch
19. Leider auch hier schlechte Dokumentation!
20. „gute Doku“ braucht feste Strukturen • korrekt • verständlich • wartbar
21. Projektbeispiel „HSQLDB“ Steckbrief Inhalt Java-basierte Datenbank, Bestandteil von OpenOffice (d.h. sehr hohe Verbreitung) Unterstützt SQL-1992 Advanced-Level, embedded-mode, (Architektur-) Dokumentation Praktisch keine verfügbar. Open-Source Datenbanksystem, kleine Entwicklergruppe, hohe Kontinuität.
22. Arc-Doku These: Hier ist „keine Arc-Doku“ angemessen, weil: Kontinuität im Entwicklungsteam > 5Jahre Massives Know-How über Codestruktur und Laufzeitverhalten - Team kann System warten und erweitern! Kaum Bedarf an Arc-Doku (sondern: User-Doku!)
23. ohne Arc-Doku... Wednesday, July 29, 2009, posted by Grady (Booch) Linux Institutional Memory A post today in Slashdot reports on the maintainer of the TTY subsystem of the Linux kernel stepping away from his role. <...> loss of intellectual capital. As I've often said, the code is the truth, but it's not the whole truth, and there's considerable architectural knowledge retained in tribal memory. <...> This is yet another reason why, <...> having a reasonably well-understood and accessible statement of a system's significant design decisions - in short, it's architecture - is important. shit happens!
24. Arc-Doku: Big-Picture Kontextabgrenzung Top-Level Bausteinsicht Details Details Laufzeit- szenarien Technische Konzepte Entwurfs- entscheidungen
25. arc42 Big-Picture ARC42 Architektur- Dokumentation 1. Einführung und Ziele 2. Randbedingungen 3. Kontextabgrenzung 4. Bausteinsicht 5. Laufzeitsicht 6. Verteilungssicht 7. Typische Muster 8. Technische Konzepte ... ... ... Logging Sicherheit Transaktionen Ergonomie Persistenz ... ... ... Logging Sicherheit Transaktionen Sessions Replikation 10. Bewertungsszenarien 9. Entwurfsentscheidungen Stakeholder- tabelle Wer? Interesse? ... ... Architektur- ziele Ziel Erklärung ... ... Verteilungssicht Laufzeitsicht Kontextabgrenzung download: www.arc42.de
26. arc42 - etwas detaillierter Anforderungsbezogene Informationen Strukturen des Systems (Sichten, Muster) Übergreifende (technische) Konzepte Entwurfsentscheidungen und Risiken
27. und noch mehr... 1. Einführung und Ziele 2. Randbedingungen 3. Kontextabgrenzung 5. Bausteinsicht 6. Laufzeitsicht 7. Verteilungssicht 8. Typische Muster und Strukturen 9. Technische Konzepte 12. Risiken 11. Qualitätsszenarien 4. Lösungsstrategie 10. Entwurfsentscheidungen 13. Glossar
28. Strukturierte Faulheit
29. Architekten verwenden (Standard-)Templates und Checklisten, um Produktivität und Qualität zu verbessern.
30. arc42: Template aus Templates
31. arc42: Template aus Templates 1 2 3 4 6 5 7 8
32. arc42 ist kostenfrei, effektiv und pragmatisch!
33. arc42 Confluence Wiki
34. arc42 Anwender Logistik Pharma Medizintechnik Elektrotechnik Robotik div. Finanzbehörden div. Versicherungen div. TelCo-Provider div. Bauspar-Träger Eisenbahntechnik Int. Flughafen Air Trafic sonst. Behörden in D, CH, A TÜV
35. Projektbeispiel „Migration“ Einführung Datenmigration, Finanzwesen, von Mainframe, (VSAM) zu Java-EE Steckbrief Einmalige Big-Bang Migration, 15-30 MA, Gesamtaufwand ca. 4500 PT sehr hohe Volatilität der Anforderungen (Architektur-) Dokumentation Praktisch keine benötigt!
36. Beispiel „Migration“ Einführung und Architekturziele Finanzdaten, höchste Anforderungen an Fehlerfreiheit und Performance Randbedingungen > 100 Millionen Datensätze, Big-Bang Migration, 24h max. Laufzeit
37. Beispiel, ausführlicher... 17 Seiten kurz!
38. Beispiel, noch ausführlicher... 43 Seiten kurz!
39. Migration (fast) ohne Arc-Doku Für‘s Projekt angemessen - in time & budget erfolgreich beendet. Team sofort in neue Projekte verschwunden! Auftraggehmer erhielt sehr ähnlichen Auftrag von anderer Behörde :-(
40. Projektbeispiel „CRM“ Inhalt RZ betreibt CRM für Massenmarkt- Anbieter (Branchen: TelCo, Finance, Energie) Steckbrief SW als Grundlage einer Hosting-CRM- Lösung, 4-7 MA, Laufzeit >24M Auftraggeber: Rechenzentrum (Architektur-) Dokumentation arc42-Struktur, Wiki+UML (+MDSD), Bestandteil der Auslieferungen!
41. Arc-Doku in CRM: Werkzeuge Ein Verantwortlicher für Doku (und Qualität!) TWiki + MagicDraw + CVS + (ant/maven) BugZilla für Anforderungen & „Tasks“
42. Arc-Doku in CRM: Prozesse Ein Verantwortlicher für Doku (und Qualität!) TWiki + MagicDraw + CVS + (ant/maven) BugZilla für Anforderungen & „Tasks“ Aus (einem kleinen Teil des) Architektur-Modell wird Code generiert. Modell nicht aktuell => Code läuft nicht
43. Arc-Doku CRM: Big-Picture MaMa Druckerei Scanner Callcenter Versender Markt- teilnehmer 1 Telefon- anbieter MoF 2 4 6 7 7 9 8 3 MaMa Input Output Reporting Configuration Operations- Monitoring Campaign Data Management Campaign Process Control Kundenstamm- & Kampagnendaten Ergebnis- daten Marktteilnehmer- daten Rohergebnis- daten Input Receiver Campaign Data Management File Filter UnMarshaller File Archiver Validator Input ErrorHandler Kundenstamm-, Kampagnen- & Rohergebnisdaten validate file archive file decrypt, unzip file create object from record read/write domain objects read file validation rules Campaign Process Control execute CampaignRules schedule Receivers CampaignProcess Control Campaign Rule Processor Campaign Data Management InOut Scheduler Process ErrorHandler determine input schedule Output Configuration read campaign rules read/write domain objects (Rete) Rule Engine Input schedule receivers Campaign Activities Controller notify init Activities fire Rules prepare Session invoke «interface» IMarkt- Teilnehmer getPrimaryKey() name vorname gebdat anrede titel «abstract» BaseMarkt- Teilnehmer «interface» IKontakt strasse nummer strZusatz etage wohnung postleitzahl ort ortsZusatz land AdresseKontakt rufnummer1 rufnummer2 stammnummer durchwahl mobilnummer1 mobilnummer2 faxnummer land erreichbarVon erreichbarBis TelefonKontakt email1 email2 homepageUrl skypeId icqId OnlineKontakt dueDate dueTime maxRepeat NextAction actionName kindOf CampaignActionType 1 * * 1 {ordered list} Markt- Teilnehmer: name: Billy Beispiel vertrag: <empty> Next ActionList: <empty> Markt- Teilnehmer: name: Billy Beispiel vertrag: T-2000 Next ActionList: <empty> Markt- Teilnehmer: name: Billy Beispiel vertrag: T-2000 Next ActionList: 1: DruckeBrief 2: InfoAnFilialen 3: InfoAnCallCenter Importiere Vertragsdaten von Mandant Schritt 1: Input- Aktivität Schritt 2: Bestimme Folgeaktivität Wenn Vertragstyp == "T-2000" Dann DruckeBrief, InfoAnFilialen und InfoAnCallCenter Entwurfsentscheidungen sind wichtig, und sollten als Grundlage der weiteren Entwickulng dem gesamten Team zur Verfügung stehen.Entwurfsentscheidungen sind wichtig, und sollten als Grundlage der weiteren Entwickulng dem gesamten Team zur Verfügung stehen.Entwurfsentscheidungen sind wichtig, und sollten als Grundlage der weiteren Entwickulng dem gesamten Team zur V erfügung stehen. Entwurfsentscheidungen sind wichtig, und sollten als Grundlage der weiteren Entwickulng dem gesamten Team zur Verfügung stehen.
44. Arc-Doku in CRM: Erfolgsmuster Einfachheit (Strukturen, Werkzeuge, Prozesse) Klare Verantwortlichkeit Doku als Bestandteil der Definition-of-Done Single-Point-of-Truth (redundanzfrei) Strukturierte Faulheit (geringer Wartungsaufwand)
45. Projektbeispiel „BigWeb“ Inhalt Webanwendung für hochvolumige finanzielle (teilweise sehr vertrauliche) Transaktionen Steckbrief Web-Anwendung mit E-Commerce für Geschäftskunden, hoher Termindruck >>80 MA Entwicklungsteam, >24 Mon. (Architektur-) Dokumentation erst 10 Monate Wiki, dann arc42 & Doku-Tooling.
46. Arc-Doku in BigWeb: Werkzeuge >8 Teilteams Erste Projektphase: MediaWiki | Visio | YEdit | ppt | Paint | MS-Word | Enterprise-Architect | <...> | Subversion | DMS oder oder oder Zweite Projektphase: Enterprise- Architect mit arc42-Struktur + Subversion
47. Arc-Doku in BigWeb: Prozessmuster Ohne Verantwortlichkeit keine Doku Heterogenität (in Werkzeugen und Doku-Prozessen) korreliert negativ mit Einfachheit, Verständlichkeit, Wartbarkeit, Füllstand (von Doku) Zeitdruck beeinträchtigt Doku Doku-Prozesse skalieren nicht Blank-Paper Syndrom behindert Fortschritt
48. Tipps für Ihre Praxis Gute Vorbilder! Beispiele guter Architekturdoku als Vorbilder oder Vorlagen.
49. Tipps für Ihre Praxis Verantwortung klären Eine Person (a.k.a. Architekt) muss Verantwortung für Qualität und Fertigstellung der Dokumentation tragen.
50. Tipps für Ihre Praxis Keine Doku => nicht fertig! Machen Sie (gute!) Doku zum Bestandteil Ihrer Auslieferungen. Ohne Doku keine Abnahme/Freigabe. Schlechte Doku ist ein Bug!
51. Tipps für Ihre Praxis Einheitliche Strukturen! Verwenden Sie Gliederungsvorlagen (z.B. arc42.de) - das erleichtert Schreiben und Lesen von Dokumentation.
53. (last and final) Tipp für Ihre Praxis Documenting doesn‘t hurt! Verwenden Sie Vorlagen und strukturierte Faulheit.