Architekturdokumentation mit Microsites

Slide 1

Slide 1 text

Mit Microsites zur Architekturvision Falk Sippach embarc Ralf D. Müller DB Systel GmbH

Slide 2

Slide 2 text

Agenda • Microsites • Architekturüberblick • Architekturüberblick as Microsite

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

Static Site Generators https://jamstack.org/generators/

Slide 5

Slide 5 text

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

Slide 6

Slide 6 text

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

Slide 7

Slide 7 text

Markdown Wir brauchen eine Erweiterung! Welche wählen wir? Funktioniert dann unsere Toolchain noch? Haben wir ein Editor-Preview?

Slide 8

Slide 8 text

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!

Slide 9

Slide 9 text

Static Site Generators https://jamstack.org/generators/ > 300 SSGs > 6 unterstützen AsciiDoc ? ? ? ? ? ?

Slide 10

Slide 10 text

Elemente einer Microsite Your Docs Search Landing Page Blog

Slide 11

Slide 11 text

Elemente einer Microsite Your Docs Search Landing Page Blog

Slide 12

Slide 12 text

Agenda • Microsites • Architekturüberblick • Architekturüberblick as Microsite

Slide 13

Slide 13 text

Softwarearchitektur auf dem Bierdeckel

Slide 14

Slide 14 text

https://blog.embarc.de/architekturueberblicke-anfertigen/ https://www.informatik- aktuell.de/entwicklung/methoden/architektur-ohne-firlefanz- ihre-loesung-auf-einem-bierdeckel.html

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

Mission Statement ◼ Plakative Darstellung der Aufgabenstellung ◼ Wenige (2 – 3) Sätze oder Stichpunkte ◼ Metapher Produktkarton

Slide 17

Slide 17 text

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)

Slide 18

Slide 18 text

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)

Slide 19

Slide 19 text

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.

Slide 20

Slide 20 text

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 ]).

Slide 21

Slide 21 text

Agenda • Microsites • Architekturüberblick • Architekturüberblick as Microsite

Slide 22

Slide 22 text

Start your Engines... • Fork Project: https://github.com/docToolchain/arc42-template-project • Build via Netlify: https://www.netlify.com/ • Edit => IntelliJ / GitHub

Slide 23

Slide 23 text

„Abheften“ in arc42 ➔https://arc42.de/

Slide 24

Slide 24 text

Arc42 im jBake Tempate arc42 by Example => https://leanpub.com/arc42byexample/c/embarcPunsch

Slide 25

Slide 25 text

ralf.d.mueller@deutschebahn.com @RalfDMueller Vielen Dank. Wir freuen uns auf Eure Fragen! falk.sippach@embarc.de @sippsack