Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Architekturdokumentation mit Microsites

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.

Ralf D. Müller

December 17, 2020
Tweet

More Decks by Ralf D. Müller

Other Decks in Programming

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