Kontinuierliche Architekturdokumentation im agilen Umfeld

Transkript

1 Kontinuierliche Architekturdokumentation im agilen Umfeld Orientation in Objects GmbH Weinheimer Str Mannheim Version:

2 Ihr Sprecher Falk Sippach Trainer, Berater, Entwickler Co-Organisator Architektur Agile Softwareentwicklung Codequalität Feedback gern Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 2

3 Java, XML und Open Source seit 1998 ) Software Factory ) ) Object Rangers ) ) Competence Center) Schlüsselfertige Realisierung von Java Software Individualsoftware Pilot- und Migrationsprojekte Sanierung von Software Software Wartung Unterstützung laufender Java Projekte Perfect Match Rent-a-team Coaching on the project Inhouse Outsourcing Schulungen, Coaching, Weiterbildungsberatung, Train & Solve-Programme Methoden, Standards und Tools für die Entwicklung von offenen, unternehmensweiten Systemen Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 3

4 Abstract Man kann zwar an vielen Stellen nachlesen, wie man Architekturdokumentation strukturiert. Aber auf der Suche nach einer praktikablen Handhabung zur Erstellung und Pflege enden die meisten Versuche in der WYSIWYG-Hölle einer Textverarbeitung oder im tiefen Schlund eines Wikis. In diesem Vortrag wollen wir uns anschauen, wie aufbauend auf bestehenden Tools und Textformaten eine möglichst redundanzfreie Dokumentation erstellt und für verschiedene Zielgruppen in ansprechenden Formaten ausgeliefert werden kann. Es wird dabei um Begriffe wie Continuous Documentation und Documentation as Code gehen. Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 4

5 Kontinuierliche Architekturdokumentation Warum? Agil? Was? Wie? 5

6 Kontinuierliche Architekturdokumentation Warum? Agil? Was? Wie? 6

7 Warum dokumentieren? Anforderungen klären Architektur bewerten Architektur entwerfen Architektur kommunizieren aus: Effektive Softwarearchitekturen 7

8 Warum dokumentieren? "In software, there is always architecture. You can t have no architecture." "But with it s documentation, there are two options: you can have one or not." "If you have one, there are two options: the documentation matches with the real architecture or not." 8

9 Warum dokumentieren? " dass auch eine perfekte Architektur nutzlos bleibt, wenn sie nicht verstanden wird " "Die Architektur zu dokumentieren, ist der kritische, krönende Schritt zur Erschaffung." Aus: Software Architecture Documentation in Practice von Bachmann, Bass 9

10 10

11 Gründe für eine Architektur-Dokumentation Entwurfsunterstützung Kommunikation Bewertbarkeit Frage nach Warum Neue Mitarbeiter Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 11

12 Kontinuierliche Architekturdokumentation Warum? Agil? Was? Wie? 12

13 Agil dokumentieren? Scrum ist "murcs" rückwärts! "Wenn ein Projekt den Bach runter geht, dann nennt man das wohl Wasserfall." 13

14 Agile Teams brauchen nicht dokumentieren! Endlich... Häh? 14

15 Wer ist schuld? Laufende Software wichtiger als ausführliche Dokumentation 15

16 Worauf das agile Manifest eigentlich abzielte Documentation through the Software Development Lifecycle Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 16

17 Agile Methoden kennen keinen Architekten! "Who needs an Architect?" 17

18 Architekt als Ratgeber/Mentor und Moderator 18

19 Vorbereiten Planen Erinnern Delegieren Integrieren Prüfen Dokumentation braucht einen Kümmerer 19

20 Agile Projekte iterativ kontinuierlich 20

21 Anpassen Reviewen Nachbessern Continuous Documentation 21

22 Redundanzen vermeidbar? Quellcode verlinken Platzhalter einbetten Single Source of Truth 22

23 Inhalte generierbar? WSDL, Swagger DB-Schema Annotationen JavaDoc 23

24 Schnittstellenbeschreibung 24

25 Validierung SanityChecks Broken Links PDFUnit 25

26 Ausführbare Dokumentation Ausführbare Tests Einbettung in Dokument Reportgenerierung 26

27 27

28 28

29 29

30 30

31 Kontinuierliche Architekturdokumentation Warum? Agil? Was? Wie? 31

32 Was dokumentieren? Inhalt 32

33 Was ist nochmal Architektur? fundamentale Strukturen, Konzepte, Entscheidungen und Lösungsansätze... die wesentlich sind, damit Systeme ihren Anforderungen genügen!... die man nicht mehr leicht losbekommt! Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 33

34 Was gehört in die Architektur-Dokumentation? Bausteine und Schnittstellen Zusammenarbeit zur Laufzeit Integration in techn. Infrastruktur Technische Konzepte Wichtige Entscheidungen Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 34

35 nur so viel wie nötig, wenig Änderungen, Zielgruppenbedürfnisse, Feedback einpflegen Pragmatik/Effektivität 35

36 Kontinuierliche Architekturdokumentation Warum? Agil? Was? Wie? 36

37 Wie dokumentieren? Prozess Werkzeugkette 37

38 Wie dokumentieren? Doku- Zielgruppen? Struktur? Werkzeuge? Medien? Grafiken? Format? 38

39 Wie dokumentieren? Doku- Zielgruppen? Struktur? Werkzeuge? Medien? Grafiken? Format? 39

40 40

41 arc42 Templates Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 41

42 Wie dokumentieren? Doku- Zielgruppen? Struktur? Werkzeuge? Medien? Grafiken? Format? 42

43 Blog/Wiki Präsentation Dokument Video, Podcast PDF HTML E-Reader Papier Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld

44 Wie dokumentieren? Doku- Zielgruppen? Struktur? Werkzeuge? Medien? Grafiken? Format? 44

45 Zielgruppen identifizieren Projektleiter Entwickler Architekt Produktmanager Fachexperten Tester Betrieb Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 45

46 Braucht jeder alles? Inhalte pro Zielgruppe festlegen möglichst ein zentrales Dokument (automatisiert) verschiedene Ausgabedokumente generieren Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 46

47 Wie dokumentieren? Doku- Zielgruppen? Struktur? Werkzeuge? Medien? Grafiken? Format? 47

48 Hauptsache, du machst es nicht mit Word! 48

49 Unser täglich Entwickler-Brot: Plain-Text Entwicklungsumgebung Kommandozeilenwerkzeuge Versionsverwaltung 49

50 Code-Nähe Ablage im Repo Versionier-/diffbar Synchrone Auslieferung Offlinefähig Teil des Build-Prozess Generierung Automatisierung Flexible Ausgabeformate Documentation as Code 50

51 Entwickler Workflow HTML PDF Leser 51

52 Alternative Datenformate Plain-Text, leicht lesbar, einfach editierbar, automatisiert verarbeitbar Plain-Text kollaborativ eingeschränkte Lesbarkeit Wikis kurz & knapp Mindmaps LaTex/DocBook Austauschformat Richtext Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 52

53 Markdown Normaler Text wird so dargestellt wie eingegeben. *Kursiv*, **Fett** und ***Fett kursiv*** bzw. _Kursiv_, Fett und Fett kursiv Markiert Text als `Inline-Quelltext` Ein Code-Block durch Einrückung mit vier Leerzeichen * Ein Punkt in einer ungeordneten Liste * Ein Unterpunkt, um vier Leerzeichen eingerückt 1. Ein Punkt in einer geordneten Liste 2. Ein weiterer Punkt 1. Noch ein Punkt bei mehrfacher Angabe derselben Ziffer # Überschrift in Ebene 1 #### Überschrift in Ebene 4 Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 53

54 AsciiDoc Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 54

55 55

56 Markup generieren JavaDoc/Annotations Enumwerte/Zustandsübergänge (Enum-Werte) Schnittstellenbeschreibung (WSDL, Swagger, WADL) DB-Schema (SchemaCrawler) Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 56

57 Tools und Sublime, Atom, IntelliJ IDEA, Eclipse, 57

58 Wie dokumentieren? Doku- Zielgruppen? Struktur? Werkzeuge? Medien? Grafiken? Format? 58

59 59

60 Tools yed ist ein kostenloses Visualisierungsprogramm und Enterprise Architect, Magic Draw, 60

61 Quelle für Bilder/Grafiken UML-Modelle Bildverarbeitung/Visualisierungsprogramme image::bild.png[alternativtext] Textuelle Beschreibung (ASCII-Art) Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 61

62 62

63 Generation Plain-Text Diagramme Quellen: Sourcecode DB-Schema XML-Modell Muss nicht aktuell gehalten werden! 63

64 64

65 Wie dokumentieren? Doku- Zielgruppen? Struktur? Werkzeuge? Medien? Grafiken? Format? 65

66 Verschiedene Szenarien 66

67 Szenario 1: Markdown, Pandoc, PlantUML, yed Schreiben in Markdown in IDE (IntelliJ IDEA) inkl. Preview PDF-Erzeugung mit PanDoc über LaTex-Zwischenschritt inkl. Corporate Design UML-Diagramme mit PlantUML, Live-Ansicht/Export aus IDE andere Diagramme mit yed, Export als *.png Stash/Bitbucket Server als Repo rendert Markdown direkt in Weboberfläche readme.md Verlinkungen auf wichtige Dokumente Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 67

68 Szenario 1: User-Feedback " fast alles ist leicht versionierund diffbar" "Generiertes PDF stellt alles bisherige in den Schatten." "Entwickler finden es klasse, Leser innerhalb der Firma: finden das generierte PDF sehr gut und hübsch." " jeder Entwickler kann ändern " "Nie wieder anders! Ich bin voll überzeugt." Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 68

69 Szenario 2: AsciiDoctor, Maven, PlantUML Erstellen AsciiDoc und PlantUML in IDE mit Preview Maven-Plugin zum Erzeugen des HTML/PDF Demo Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 69

70 Szenario 3: Generierung aus Quellcode Quellcode parsen Reflection Spring Kontext in Unit-Test aus Klassen-Strukturen Diagramm-Markup erzeugen z. B. PlantUML als Text-Datei ablegen und in Markup-Dokumentation verlinken im Build-Prozess als Input für Markup-Konvertierung einlesen Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 70

71 Szenario 4: Schnittstellenbeschreibung Generierung aus WSDL, WADL, Swagger Einbindung in Build-Prozess Swagger2Markup JAX-RS Analyzer Spring REST Docs Demo Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 71

72 Szenario 5: Ausführbare Dokumentation Quellcode-Struktur in Graph-Datenbank importieren Architektur-Regeln als Graph-Abfragen in AsciiDoc einbetten Demo Orientation in Objects GmbH Kontinuierliche Architekturdokumentation im agilen Umfeld 72

73 Wie dokumentieren? Doku- Zielgruppen? Struktur? Werkzeuge? Medien? Grafiken? Format? 73

74 Wiki 74

75 Zusammenarbeit Verlinkung Review-/Redaktions-Prozess Prozess-Unterstützung Abbildung Workflow Erweiterung über Plugins Alles in einer Box! 75

76 Strukturiert? Plain-Text? Offlinefähigkeit? Versionierung? Code-Nähe? Automatisierung? Druckausgabe? Zielgruppen? Kontextwechsel Schlund des Wiki 76

77 Tasks Mentions Kommentare Jira 77

78 Balsamiq Mockups Gliffy (Diagramme, UML) 78

79 ??? Fragen?? Orientation in Objects GmbH? Weinheimer Str Mannheim 79

80 Vielen Dank für Ihre Aufmerksamkeit! Orientation in Objects GmbH Weinheimer Str Mannheim