Architekturdokumentation mit Microsites

Embarc Architektur-Punsch, zusammen mit Falk Sippach
https://blog.embarc.de/architektur-punsch-2020/#workshop4

Dokumentation in Markdown oder AsciiDoc zu erstellen, ist einfach und besonders bei Entwicklern beliebt. Die Inhalte liegen nicht nur nahe beim Quellcode, sie können auch direkt mit den gleichen Werkzeugen verfasst und automatisiert weiter bearbeitet werden (Documentation as Code). Gängige Texteditoren und IDEs bieten Editierhilfen und Vorschaufunktionen, die bekannten Code-Repositories (GitHub, GitLab, ...) rendern die Dokumente zudem in der Vorschau als HTML-Seiten. Im nächsten Schritt kann man daraus eine Landingpage (öffentlich oder auch nur fürs Intranet) fürs eigene Projekt bauen - der Architekturüberblick als Microsite.

Allen Beteiligten vom neuen Mitarbeiter bis hin zum Management ermöglicht man so einen intuitiven Einstieg ins Projekt. Durch frei verfügbarer Layouts kann diese Webseite aber nicht nur schick aussehen, sie lässt sich auch einfach pflegen und leicht aktuell halten. Statische Seitengeneratoren wie Jekyll, Hugo oder JBake bieten dabei den Rahmen und mit wenig Aufwand lassen sich die Inhalte zusammenfügen, einzelne Teile aus dem Quellcode oder den Datenmodellen generieren, Newsfeeds erstellen, Grafiken über Textformate wie PlantUML einbinden und potentiell auch Strukturvorlagen wie arc42 integrieren. Dank gestiegener Akzeptanz beim Erstellen erhalten wir so eine qualitativ hochwertige Dokumentation, die von allen wahrgenommen und gern konsumiert wird.

Transcript

1. Mit Microsites zur Architekturvision Falk Sippach embarc Ralf D. Müller DB Systel GmbH
2. Agenda • Microsites • Architekturüberblick • Architekturüberblick as Microsite
3. Als Microsite (bzw. Mikro-Website) bezeichnet man im Webdesign eine schlanke Website mit wenigen Unterseiten und geringer Navigationstiefe innerhalb eines größeren Internet-Auftritts. Die Microsites sind optisch von der eigentlichen Website unabhängig und bilden thematisch und gestalterisch eine eigenständige kleine Internetpräsenz. https://de.wikipedia.org/wiki/Microsite
4. Static Site Generators https://jamstack.org/generators/
5. Markdown • Markdown • Toller Standard für einfache Auszeichnungen • Features Span Elements Links Emphasis Code Images Block Elements Paragraphs and Line Breaks Headers Blockquotes Lists Code Blocks Horizontal Rules TOC Tables (Feature Rich) Includes (Level-Offset) PlantUML Admonitions Attributes Anchors Footnotes, Index, Glossary Videos Syntax Highlighting Callouts Math Rendering Outputformats
6. Markdown Wir brauchen eine Erweiterung! Welche wählen wir? •CommonMark •CriticMarkup •Discount •DocFX •ExtraMark •Ghost's Markdown/Haunted Markdown •GitHub Flavored Markdown •GitLab Flavored Markdown (with login) •Haroopad Flavored Markdown •iA Writer's Markdown •Kramdown •Leanpub Flavored Markdown •Litedown •Lunamark •Madoko •Markdown •Markdown 2 •Markdown Extra •Markdown-it •Markua •Maruku •MultiMarkdown •Pandoc's Markdown •PHP Markdown Extra Extended •Python Markdown •R Markdown •Redcarpet •Remarkable •Rhythmus •Scholarly Markdown •Showdown •StackOverflow's Markdown •Taiga Markdown •Trello's Markdown •vfmd •Xcode/Swift Playgrounds Markup https://github.com/commonmark/commonmark-spec/wiki/markdown-flavors
7. Markdown Wir brauchen eine Erweiterung! Welche wählen wir? Funktioniert dann unsere Toolchain noch? Haben wir ein Editor-Preview?
8. AsciiDoc / Asciidoctor leistungsfähige Syntax für technische Dokumentation in Ruby geschrieben mit Opal nach JavaScript transpiliert mit jRuby auf der JVM gewrapped => Keine Dialekte!
9. Static Site Generators https://jamstack.org/generators/ > 300 SSGs > 6 unterstützen AsciiDoc ? ? ? ? ? ?
10. Elemente einer Microsite Your Docs Search Landing Page Blog
11. Elemente einer Microsite Your Docs Search Landing Page Blog
12. Agenda • Microsites • Architekturüberblick • Architekturüberblick as Microsite
13. Softwarearchitektur auf dem Bierdeckel
14. https://blog.embarc.de/architekturueberblicke-anfertigen/ https://www.informatik- aktuell.de/entwicklung/methoden/architektur-ohne-firlefanz- ihre-loesung-auf-einem-bierdeckel.html
15. Was ist ein Architekturüberblick? Ein Architekturüberblick macht die zentralen Lösungsansätze Eurer Softwarearchitektur für Außenstehende nachvollziehbar. Teamfremde Kollegen Entscheider Stakeholder Neue Teammitglieder
16. Mission Statement ◼ Plakative Darstellung der Aufgabenstellung ◼ Wenige (2 – 3) Sätze oder Stichpunkte ◼ Metapher Produktkarton
17. Kontextabgrenzung Abgrenzung des Systems und Visualisierung der Benutzer und Fremdsysteme, mit denen es interagiert. Form: Graphik, ergänzt um kurze Beschreibungen. Fremdsysteme Benutzer System (Blackbox)
18. Einflüsse auf Entscheidungen - schränken die Lösung ein - schließen Optionen aus - prägen die Lösung - nachher schwierig “einzubauen” Qualitätsanforderungen Benutzbarkeit, Effizienz, Wartbarkeit, Sicherheit ... Vorgaben/Rahmenbedingungen Technisch (z.B. Datenbankprodukt) Organisatorisch (z.B. Team)
19. Qualitätsziele ◼ Die wichtigsten geforderten Qualitätsmerkmale für ein Softwaresystem (Synonym: Architekturziele). ◼ Typischerweise werden als Qualitätsziele im Rahmen eines Architekturüberblicks die Top-3 bis Top-5 genannt.
20. Architektur- /Lösungsansätze Architektur- /Qualitätsziele Lösungsstrategie Stellt Qualitätsziele und zugeordnete high-level Lösungsansätze in Beziehung zueinander dar. Form: Tabelle ([ Ziele | Lösungsansätze ]).
21. Agenda • Microsites • Architekturüberblick • Architekturüberblick as Microsite
22. Start your Engines... • Fork Project: https://github.com/docToolchain/arc42-template-project • Build via Netlify: https://www.netlify.com/ • Edit => IntelliJ / GitHub
23. „Abheften“ in arc42 ➔https://arc42.de/
24. Arc42 im jBake Tempate arc42 by Example => https://leanpub.com/arc42byexample/c/embarcPunsch
25. ralf.d.mueller@deutschebahn.com @RalfDMueller Vielen Dank. Wir freuen uns auf Eure Fragen! falk.sippach@embarc.de @sippsack