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

Hitchhikers Guide to Architecture Documentation

Hitchhikers Guide to Architecture Documentation

Together with Ralf D. Müller:

Use AsciiDoctor and simple automation to treat your (architecture) documentation like source code - close to your IDE, ideally suited for practical developers

Dr. Gernot Starke

September 18, 2017
Tweet

More Decks by Dr. Gernot Starke

Other Decks in Programming

Transcript

  1. Hitchhikers Guide to
    Architecture Documentation
    arc42, AsciiDoc und Co. in Aktion
    Ralf D. Müller & Gernot Starke

    View full-size slide

  2. Ralf D. Müller
    Bei Tag Solution Architect
    in der Digital Factory
    der Deutschen Bank.
    In der Freizeit Geek:
    § Web-Technologien
    § Qualität (Security, Testautomation)
    § Produktivität (Gradle, Groovy, Grails)
    Maintainer von docToolchain

    View full-size slide

  3. Dr. Gernot Starke
    innoQ Fellow
    Softwarearchitektur
    § Entwurf
    § Evolution + Modernisierung
    § Dokumentation
    § Reviews
    +49 177 7282570
    [email protected]

    View full-size slide

  4. Das erwartet Sie !
    §praktische Architekturdokumentation
    §Tipps zu arc42 und docs-like-code
    §Experimentelle Features :-)
    §Vorschläge aus Erfahrung
    NSB (No Silver Bullet)

    View full-size slide

  5. „Schrank“ für Architektur-Info
    Anforderungen
    Entscheidungen
    Strukturen von
    Sourcecode

    View full-size slide

  6. Beispiel (CRM-System, 2000+ PT)

    View full-size slide

  7. Beispiel (Datenmigration, 4000+ PT)

    View full-size slide

  8. Tabellen
    Text
    Diagramme
    Verzeichnisse

    View full-size slide

  9. Stakeholder von Doku
    Breites Spektrum...
    Management, Auftraggeber, Projekt-Steuerkreis, sonstige Projekt-Gremien, PMO, Product-
    Owner, Projektmanager, Produktmanager, Fachbereich, Unternehmens-/Enterprise-
    Architekt, Architektur-Abteilung, Methoden-Abteilung, QS-Abteilung, IT-Strategie,
    Softwarearchitekten, Software-Designer, Entwicklungsteam, Tester,
    Konfigurationsmanager, Build-Manager, Release-Manager, Wartungsteam, externe Dienstleister,
    Zulieferer, Hardware-Designer, Rollout-Manager, Infrastruktur-Planer, Security, Behörde,
    Aufsichtsgremium, Auditor, Mitbewerber/Konkurrent, Endanwender, Fachpresse, Fachadministrator,
    Systemadministrator, Ops-Team, Operator, Hotline, Betriebsrat, Lieferant von
    Standardsoftware, verbundene Projekte, API-Nutzer, Normierungsgremium, Gesetzgeber...

    View full-size slide

  10. VENOM
    § VEry NOrMal System
    § Gewachsenes System
    § Unterschiedliche Stakeholder
    § Hoher Pflegeaufwand

    View full-size slide

  11. Geoff – Solution Architect
    §... für VENOM
    §solider technischer Background
    Aufgaben (u.a.):
    §Evolution des Systems
    §Dokumentation + Kommunikation
    der Architektur

    View full-size slide

  12. Methodik-
    Modularisiere Dokumentation
    großer Systeme!
    Eigene Dokumente für
    relevante Teilsysteme
    Siehe: http://faq.arc42.org/questions/J-1/
    VENOM Architecture
    1. Einführung und Ziele
    3. Kontextabgrenzung
    5. Bausteinsicht
    8. Konzepte
    4. Lösungsstrategie
    12. Glossar
    11. Risiken & techn. Schulden
    VENOM-Commons
    1. Einführung und Ziele
    2. Randbedingungen
    3. Kontextabgrenzung
    5. Bausteinsicht
    6. Laufzeitsicht
    7. Verteilungssicht
    8. Konzepte
    10. Qualitätsszenarien
    9. Entwurfsentscheidungen
    4. Lösungsstrategie
    12. Glossar
    VENOM-NGO
    5. Bausteinsicht
    6. Laufzeitsicht
    7. Verteilungssicht
    Private-Customer…
    8. Konzepte
    9. Entwurfsentscheidungen
    4. Lösungsstrategie
    Ziele des Gesamtsystems
    Wesentliche Qualitätsanforderungen
    strategische Entscheidungen
    Bausteinsicht Level-1
    zentrale Konzepte
    Übergreifend genutzte Begriffe
    Verweise Verweise Verweise

    View full-size slide

  13. Methodik-
    Trenne Projekt- von Systemdokumentation!
    Projektdokumentation
    ~arc42 „locker“
    Diskussionen
    Implementation-Guide,
    Tasks / Issues
    Systemdokumentation
    Weitere relevante Infos...
    (Betrieb/Admin, Test, Release...)
    11. Risiken
    ARC42
    Architektur-Dokumentation
    1. Einführung und Ziele
    2. Randbedingungen
    3. Kontextabgrenzung
    5. Bausteinsicht
    6. Laufzeitsicht
    7. Verteilungssicht
    8. Konzepte
    10. Qualitätsszenarien
    9. Entwurfsentscheidungen
    4. Lösungsstrategie
    12. Glossar
    Team „Gärtner“

    View full-size slide

  14. Methodik-
    Dokumentiere
    sparsam!
    Siehe: http://docs.arc42.org/keywords/#lean
    •Tip 3-5: Restrict the context to an overview, avoid too many details!
    •Tip 3-6: Simplify the context by categorization!
    •Tip 4-1: Explain the solution strategy as compact as possible (e.g. as list of keywords)!
    •Tip 4-2: Describe the solution approaches as a table!
    •Tip 4-5: Let the solution strategy grow iteratively / incrementally!
    •Tip 5-3: Always describe level-1 of the building block view ('Level-1 is your friend')!
    •Tip 5-6: Hide the inner workings of blackboxes!
    •Tip 6-2: Document only a few runtime scenarios!
    •Tip 6-3: Document 'schematic' (instead of detailed) scenarios!
    •Tip 6-9: Use a textual notation to describe runtime scenarios!
    •Tip 7-7: Use tables to document software/hardware mapping!!
    •Tip 8-1: Explain the Concepts!
    •Tip 8-9: Document decisions instead of concepts!
    •Tip 9-1: Document only architecturally relevant decisions!
    •Tip 9-7: Document decisions informally as a blog (RSS-feed)!
    •Tip 12-2: Document the glossary as a table!
    •Tip 12-5: Keep the glossary compact! Avoid trivia.
    •Tip 12-6: Make your 'product owner' or 'project manager' responsible for the glossary
    •Tip 1-16: Describe only the top 3-5 quality goals in the introduction!
    •Tip 1-22: Skip the stakeholder table if your management already maintains it!
    •Tip 1-23: Classify your stakeholders by interest and influence!
    •Tip 3-17: Combine business context with technical information!
    •Tip 3-19: Defer technical context to the deployment view!
    •Tip 5-10: Use crosscutting concepts to describe or specify similarities in building blocks!
    •Tip 5-15: Align the mapping of source-code to building-blocks along the directory and file structure!
    •Tip 6-10: Use both small and large building blocks in scenarios!
    •Tip 7-10: Leave hardware decisions to hardware-experts!
    •Tip 8-10: Use the collection from arc42 as checklist for concepts!
    •Tip 5-21: Describe or specify internal interfaces with minimal effort!

    View full-size slide

  15. Teil 2: Docs-as-Code

    View full-size slide

  16. Format der Dokumentation (1)
    • MS Word: etablierter Standard
    • aber:
    • Diagramme?
    • Quellcode integrieren?
    • Teamarbeit?
    • Versionierung?
    • diff/merge?
    • Geek-Akzeptanz?
    • Build-Integration?

    View full-size slide

  17. §Dokumentation wie Code
    (Plain-Text)
    • Diagramme!
    • Quellcode integrieren!
    • Teamarbeit!
    • Versionierung!
    • diff/merge!
    • Geek-Akzeptanz!
    • Build-Integration!

    View full-size slide

  18. arc42 Formate
    §AsciiDoc: flexibelstes Format
    (unserer Meinung nach)
    §In viele andere Formate transformierbar
    (fast immer verlustfrei)

    View full-size slide

  19. Demo
    01-SimpleBuild
    git clone
    [email protected]:arcSummit2017/examples.git

    View full-size slide

  20. Demo
    01-SimpleBuild

    View full-size slide

  21. build.gradle demo.adoc console output
    = A first Headline
    And a first paragraph.
    It continuous on the next headline
    Second paragraph.
    == Second-Level Headline
    A link to http://asciidoctor.org/docs[Asciidoctor.org]
    Demo

    View full-size slide

  22. build.gradle demo.adoc console output
    plugins { id "org.asciidoctor.convert" version "1.5.3" }
    Demo – eine erste Konvertierung

    View full-size slide

  23. build.gradle demo.adoc console output
    PS C:\Users\Demo\jax2017\demo1> gradle asciidoc
    :asciidoctor
    io/console not supported; tty will not be manipulated
    BUILD SUCCESSFUL
    Total time: 4.554 secs
    PS C:\Users\Demo\jax2017\demo1>
    Demo – eine erste Konvertierung

    View full-size slide

  24. build.gradle demo.adoc console output
    Demo – eine erste Konvertierung
    http://asciidoctor.org/docs/render-documents/

    View full-size slide

  25. Tools zur Konvertierung
    §Geringste Einstiegshürde:
    Gradle und asciidoctorj
    §Maven ist aufwändiger, gut unterstützt
    §Gradle bezüglich weiterer Build-Steps flexibler
    01-SimbleBuild

    View full-size slide

  26. Out-of-the-Box: docs-as-code
    • „ablenkungsfrei“ –
    Dokumentation wie Code oder eMails schreiben
    • modularisierbar
    • Bilder referenziert, nicht eingebettet
    • Integration von Source-Code
    • Reviews, Pull-Requests, Versionierung durch Git
    • Konvertierung nach HTML5, DocBook u.v.a.

    View full-size slide

  27. .adoc
    .adoc
    …die Reise beginnt erst
    § Geoff bisher zufrieden
    § alte Dokumentation überführen...
    .docx .adoc .html

    View full-size slide

  28. treat Docs-as-Code
    § Geoff erkennt, dass die Transformation nach AsciiDoc erst
    der Anfang war
    § Als nächstes möchte er durch den Docs-as-Code Ansatz die
    Überarbeitung der Dokumentation weiter vereinfachen

    View full-size slide

  29. treat Docs-as-Code I: Version Control
    .adoc
    .adoc
    .adoc .html

    View full-size slide

  30. treat Docs-as-Code II: Git-Flow
    .adoc
    .adoc
    .adoc .html
    Fork
    PR
    .adoc

    View full-size slide

  31. treat Docs-as-Code III: Build-Server
    .adoc
    .adoc
    .adoc .html
    Fork
    PR
    .adoc
    Build-
    Server
    On Change
    Publish

    View full-size slide

  32. Teil 3: AsciiDoc 101

    View full-size slide

  33. AsciiDoc 101
    Tabellen
    Text
    Diagramme
    Verzeichnisse,
    Nummerierung
    Headings
    Verweise
    Fußnoten
    Kästen
    Sourcecode

    View full-size slide

  34. Cheatsheet:
    http://powerman.name/doc/asciidoc

    View full-size slide

  35. Ascii{Doctor|Doc}?
    • AsciiDoc:
    • Format (Syntax) einer Sprache zum Erstellen von Dokumenten
    • Python-basierter „Übersetzer“
    • OpenSource-Projekt seit 2002, letzte Version von 2013
    • AsciiDoctor
    • Ruby-basierter (schneller!) Übersetzer von AsciiDoc-Dokumenten
    • (nahezu) vollständig kompatibel zu AsciiDoc
    • Aber: Transformation in definierten Phasen, d.h. programmatischen Einfluss
    auf Übersetzung
    • enthält (wenige) Erweiterungen gegenüber AsciiDoc

    View full-size slide

  36. Text – bei Bedarf auch schön...
    forced + line break
    forced
    line break
    normal, _italic_, *bold*, +mono+. ``double
    quoted'', `single quoted'.
    normal, ^super^, ~sub~.
    normal, italic, bold, mono.
    “double quoted”, ‘single quoted’.
    normal, super, sub
    .
    Command: `ls -al` +
    mono *bold*+
    `passthru *bold*`
    Command: ls -al
    mono bold
    passthru *bold*
    Path: '/some/filez.txt', '.b' Path: /some/filez.txt, .b
    [red]#red text# [yellow-background]#on
    yellow# [big]#large# [red yellow-background
    big]*all bold*
    red text on yellow large all bold

    View full-size slide

  37. Headings – Struktur in Dokumenten (1)
    == Level 1
    Text.
    === Level 2
    Text.
    ==== Level 3
    Text.
    ===== Level 4
    Text.
    Level 1
    Text.
    Level 2
    Text.
    Level 3
    Text.
    Level 4
    Text.

    View full-size slide

  38. Headings (2) Präambel
    • Pfade
    • i18n Einstellungen

    View full-size slide

  39. Diagramme & Bilder (1)
    === Business Context
    image::hsc-context.png[title="Business Context"]

    View full-size slide

  40. Diagramme & Bilder (1b)
    === Business Context
    .Business Context
    image::hsc-context.png[]

    View full-size slide

  41. Diagramme (2)
    === Images
    image::plain.png[]
    image::withCaption.png[title=“Bild-Unterschrift"]
    .Bild-Unterschrift
    image::someImage.png[]
    image::full.png[„alt“,title=“caption"]

    View full-size slide

  42. Diagramme (3)
    :imagesdir: ../images
    image::plain.png[]
    Pfad relativ zu „imagesDir“
    Default-Pfad für Bilder

    View full-size slide

  43. Diagramme (4): Größe
    image::sized.png[„alt“, 600, 400]
    Breite (width)
    Höhe (height)
    image::sized.png[„alt“, width=600, height=400]

    View full-size slide

  44. Verweise (1)
    Dokument-intern
    • Verweise auf Überschriften
    • Verweise auf beliebige Textpassagen (z.B. Glossareintrag)
    • Literaturverweise
    • Verweise aus HTML ImageMaps
    Externe Links

    View full-size slide

  45. Siehe <>.
    [[Kontextabgrenzung]]
    === Kontextabgrenzung
    image::context.png[]
    Verweise (2)
    der Verweis...
    Sprungziel („target“, ID)

    View full-size slide

  46. Siehe <>.
    === Kontextabgrenzung
    image::context.png[]
    Verweise (3) „DRY“
    Default-ID:
    Aus Heading generiert

    View full-size slide

  47. Siehe <>.
    [[context, Kontext]]
    === Kontextabgrenzung
    image::context.png[]
    Verweise (4)
    der Verweis...
    Sprungziel („target“, mit
    Symbol und Name)

    View full-size slide

  48. Tabellen
    in arc42 für:
    • Stakeholder
    • Qualitätsanforderungen / -szenarien
    • externe Schnittstellen
    • Whitebox-Template
    • Risiken
    • Glossar

    View full-size slide

  49. Tabellen (1)
    |===
    |column 1, row 1 |column 2, row 1 |column 3, row 1
    |column 1, row 2 |column 2, row 2 |column 3, row 2
    |===

    View full-size slide

  50. Tabellen mit Header
    [cols=3,options="header"]
    |===
    |Header-1 | Header-2 | Header-3
    |c1r1 |c2r1 |c3r1
    |c1r2
    |c2r2
    |c3r2
    |===
    Layout über Optionen
    steuern:
    • Anzahl Spalten
    • Header/Footer
    • (relative) Spaltenbreite
    • links-/rechtsbündig,
    zentriert

    View full-size slide

  51. Tabellen mit Spaltenbreiten
    [cols="1,2,4"]
    |===
    |Cell in column 1, row 1
    |Cell in column 2, row 1
    |Cell in column 3, row 1
    |Cell in column 1, row 2
    |Cell in column 2, row 2
    |Cell in column 3, row 2
    |===
    relative (!) Breite

    View full-size slide

  52. Kästen („admonitions“)

    View full-size slide

  53. Kästen („admonitions“)

    View full-size slide

  54. Editoren für AsciiDoc
    •(plaintext) Editor
    • Atom, brackets.io, Sublime, VS-Code, vi & Co.
    •Editor der IDE
    • IntelliJ, Eclipse
    •spezielle AsciiDoc-Tools
    • AsciiDocFX
    • AsciiDocLive (https://asciidoclive.com)
    • Live-Reload Browser Extensions

    View full-size slide

  55. Atom • Syntax Highlighting
    • Preview
    • (Autocompletion)

    View full-size slide

  56. IntelliJ • Syntax Highlighting
    • Preview

    View full-size slide

  57. IntelliJ (2) • versteht geschachtelte Includes

    View full-size slide

  58. AsciiDocLive • Syntax Highlighting
    • Preview
    • Browser-basiert
    • Lokal installierbar

    View full-size slide

  59. AsciiDocFX • Syntax Highlighting
    • Preview
    • diverse Erweiterungen (Formeln, Diagramme etc)
    • JavaFX basiert
    • Mac, Win, Linux

    View full-size slide

  60. AsciiDocFX • versteht (geschachtelte) includes...

    View full-size slide

  61. Unterdokumente
    §Setzen von imagedir am Anfang jedes Dokuments:
    ifndef::imagesdir[:imagesdir: ../../images]
    §Partielle Includes
    include::subdocument.adoc[tags=xyz]
    §Korrektur von Überschriften-Level
    include::subdocument.adoc[tags=xyz, leveloffset=+1]

    View full-size slide

  62. Teil 4: Modulare Doku

    View full-size slide

  63. Modulare Doku...
    Einstieg
    Doku-Teile
    include

    View full-size slide

  64. Dateien einfügen..
    == Hier ein Text...
    include::part1.adoc[]
    File: master.adoc
    Dies ist Teil 1.
    File: part1.adoc

    View full-size slide

  65. Demo
    02-Modules
    git clone
    [email protected]:arcSummit2017/examples.git

    View full-size slide

  66. VENOM Dokumente...
    Architekturdoku
    Doku des
    Unternehmens +
    der IT-Prozesse

    View full-size slide

  67. Modularisierung in VENOM (2)
    Master-Dokumente

    View full-size slide

  68. Anforderungen
    Entscheidungen
    Strukturen von
    Sourcecode

    View full-size slide

  69. Modularer
    Aufbau
    arc42, Version 7.0, Stand März 2017.
    © Dr. Peter Hruschka und Dr. Gernot Starke.
    Frei für kommerzielle und private Nutzung.
    1. Einführung und Ziele
    1.1 Aufgabenstellung
    1.2 Qualitätsziele
    1.3 Stakeholder
    7.Verteilungssicht
    7.1 Infrastruktur Ebene 1
    7.2 Infrastruktur Ebene 2
    ….
    2. Randbedingungen
    2.1 Technische Randbedingungen
    2.2 Organisatorische Randbedingungen
    2.3 Konventionen
    3. Kontextabgrenzung
    3.1 Fachlicher Kontext
    3.2 Technischer- oder Verteilungskontext
    4. Lösungsstrategie
    5. Bausteinsicht
    5.1 Ebene 1
    5.2 Ebene 2
    ….
    6. Laufzeitsicht
    6.1 Laufzeitszenario 1
    6.2 Laufzeitszenario 2
    ….
    8. Querschnittliche Konzepte
    8.1 Fachliche Struktur und Modelle
    8.2 Architektur- und Entwurfsmuster
    8.3 Unter-der-Haube
    8.4 User Experience
    ….
    9. Entwurfsentscheidungen
    9.1 Entwurfsentscheidung 1
    9.2 Entwurfsentscheidung 2
    ….
    10. Qualitätsanforderungen
    10.1 Qualitätsbaum
    10.2 Qualitätsszenarien
    11. Risiken und technische Schulden
    12. Glossar

    View full-size slide

  70. Demo
    03-arc42
    git clone
    [email protected]:arcSummit2017/examples.git

    View full-size slide

  71. Demo
    03-arc42

    View full-size slide

  72. Weitere Infos + Beispiele
    https://leanpub.com/arc42byexample/c/arc42-sagt-danke-2017

    View full-size slide

  73. Dateien einfügen (ein Problem)..
    == Bar-API
    include::real.adoc[]
    File: bar.adoc
    == Real-Info
    You need to know...
    File: real.adoc
    ==== Foo-API Doc
    include::real.adoc[]
    File: foo.adoc
    ??

    View full-size slide

  74. Korrektur von Header-Levels
    include::part1.adoc[leveloffset=+1]

    View full-size slide

  75. Modular++: Partielles Einfügen

    View full-size slide

  76. Spezialitäten bei Includes...
    §Partielle Includes für Quellcode
    include::FooBarApi.java[tags=xyz]
    §Korrektur von Überschriften-Level
    include::subdocument.adoc[tags=xyz, leveloffset=+1]

    View full-size slide

  77. Teil 5: Diagramme

    View full-size slide

  78. Diagramme
    • Geoff stört der hohe Pflegeaufwand für Diagramme
    • Beherrscht AsciiDoc nicht PlantUML?

    View full-size slide

  79. Diagramme: PlantUML

    View full-size slide

  80. Demo
    04-PlantUML
    git clone
    [email protected]:arcSummit2017/examples.git

    View full-size slide

  81. Demo
    04-PlantUML

    View full-size slide

  82. Diagramme: PlantUML
    .Benutzer und Benutzergruppen von VENOM
    [plantuml]
    ----
    !pragma graphviz_dot jdot
    :Private User: as private
    :User Groups: as groups
    :Corporate Users: as corporate
    :Government Users: as gov
    :Regulation &\nStandard Bodies: as bodies
    :Operations: as ops
    :internal Users: as internal
    (VENOM\ni.B.O.S.S) as venom
    private -right-> venom
    groups --> venom
    corporate --> venom
    gov -up-> venom
    bodies -up-> venom
    ops --> venom
    internal -left-> venom
    ----

    View full-size slide

  83. Diagramme als Plain-Text: PlantUML
    • http://plantuml.com/
    • http://asciidoctor.org/docs/asciidoctor-diagram/
    Nicht alle Diagrammtypen sind für PlantUML gleichgut geeignet.
    Sequenzdiagramme sind jedoch ein sehr guter Anwendungsfall!

    View full-size slide

  84. Asciidoctor Plugins
    § AsciidoctorJ oder jRuby?
    § Bei PlantUML Verschiedene Output-Formate beachten!

    View full-size slide

  85. Diagramme
    § In welche Richtung zeigen die Pfeile im Diagramm?
    § Datenfluss?
    § Aktivierung?
    § Abhängigkeit?
    § => Im Zweifel Pfeile immer vom Aufrufenden zum Aufgerufenen
    … und in der Legende erklären
    § Noch keinen eigenen Stil gefunden?
    => C4 von Simon Brown ist ein guter Start
    http://www.codingthearchitecture.com/2014/08/24/c4_model_poster.html

    View full-size slide

  86. Diagramme: Modellierung
    §Geoff nutzt ein UML-Modellierungstool
    §Einbetten der Grafiken schwerfällig
    §Notizen im UML-Modell gehen in Doku verloren

    View full-size slide

  87. treat Docs-as-Code IV: automate
    Betreiber und Administratoren
    von VENOM
    Flexibilität hinsichtlich
    Betriebsumgebung,
    Betriebssystem. Möglichst
    wenig Aufwand bei technischer
    Administration und
    Inbetriebnahmen. Technisches
    Monitoring.

    View full-size slide

  88. treat Docs-as-Code IV: automate
    {adoc:stakeholder}
    | Operations
    | Betreiber und
    Administratoren von VENOM
    | Flexibilität hinsichtlich
    Betriebsumgebung,
    Betriebssystem. Möglichst
    wenig Aufwand bei technischer
    Administration und
    Inbetriebnahmen. Technisches
    Monitoring.

    View full-size slide

  89. === Stakeholder
    ==== Benutzer und Benutzergruppen
    [[figure-users]]
    image::ea/1.5_Stakeholder.png[title="Benutzer und Benutzergruppen
    von VENOM"]
    [cols="2,3,3,2" options="header"]
    .Benutzer und Benutzergruppen
    |===
    | Rolle | Beschreibung | Ziel | Bemerkungen
    include::../../ea/stakeholder.ad[]
    |===
    treat Docs-as-Code IV: automate

    View full-size slide

  90. treat Docs-as-Code IV: automate

    View full-size slide

  91. Demo
    05-EnterpriseArchitect
    git clone
    [email protected]:arcSummit2017/examples.git

    View full-size slide

  92. Demo
    05-EnterpriseArchitect

    View full-size slide

  93. Teil 6: Stakeholder

    View full-size slide

  94. Stakeholder
    § Geoff bemerkt schnell, dass nicht jeder mit einer online
    HTML-Dokumentation glücklich ist
    § Er muss für unterschiedliche Stakeholder die Dokumente
    auch unterschiedlich aufbereiten

    View full-size slide

  95. .docx bzw. MS Word
    http://pandoc.org

    View full-size slide

  96. .docx bzw. MS Word

    View full-size slide

  97. Export PPT
    Aufgabe:
    Powerpoint in Doku integrieren:
    § Sprechernotizen enthalten
    asciidoc
    § Slides und asciidoc werden
    automatisch exportiert

    View full-size slide

  98. Demo
    08-PPTX
    git clone
    [email protected]:arcSummit2017/examples.git

    View full-size slide

  99. Überarbeiten in PDF
    § … geht fast besser, als in Word

    View full-size slide

  100. Demo
    07-PDF
    git clone
    [email protected]:arcSummit2017/examples.git

    View full-size slide

  101. PDF-Header
    header:
    height: 0.75in
    line_height: 1
    recto_content:
    right: 'image:logo.jpg[width="30"]'
    center: 'VENOM: {document-subtitle}'
    verso_content:
    left: 'image:logo.jpg[width="30"]'
    center: 'VENOM: {document-subtitle}'
    custom-theme.yml

    View full-size slide

  102. Seitenumbrüche
    § …machen keinen Sinn für Single-Page HTML
    § …aber für PDF!
    § <<<<

    View full-size slide

  103. Confluence
    § Aber alle anderen Dokumente sind in Confluence…
    § Confluence speichert die Seiten intern als xhtml
    § …und hat eine REST-API
    § et voilá…

    View full-size slide

  104. Zusammenarbeit

    View full-size slide

  105. Zusammenarbeit

    View full-size slide

  106. Zusammenarbeit

    View full-size slide

  107. Zusammenarbeit

    View full-size slide

  108. Zusammenarbeit

    View full-size slide

  109. Zusammenarbeit

    View full-size slide

  110. Changelog
    10-Changelog
    git clone
    [email protected]:arcSummit2017/examples.git

    View full-size slide

  111. Changelog
    09-Changelog

    View full-size slide

  112. Teil 7: Test der Doku

    View full-size slide

  113. Broken Links
    §...immer wieder mit Probleme bei
    Dateinamen oder Hyperlinks
    §Lösung: automatisierte Tests!
    §Inhaltliche Fehler (praktisch) nicht testbar...

    View full-size slide

  114. Mögliche (Verweis-)Fehler bei Doku
    §Broken Cross References (aka Broken Links)
    §Missing Images
    §Missing Resources
    §Multiple Definitions of link targets (ID‘s)
    §Missing Alt-tags in Images
    https://github.com/aim42/htmlSanityCheck

    View full-size slide

  115. Ziel: (Unit-)Test
    https://github.com/aim42/htmlSanityCheck

    View full-size slide

  116. htmlSanityCheck

    View full-size slide

  117. Demo
    11-htmlSanityCheck
    git clone
    [email protected]:arcSummit2017/examples.git

    View full-size slide

  118. Demo
    11-htmlSanityCheck

    View full-size slide

  119. Kann noch mehr getestet werden?

    View full-size slide

  120. Demo
    12-AutomatedTests
    git clone
    [email protected]:arcSummit2017/examples.git

    View full-size slide

  121. Bonus 1: Tabellen mit Excel
    13-Excel
    git clone
    [email protected]:arcSummit2017/examples.git

    View full-size slide

  122. Bonus 1: Tabellen mit Excel
    13-Excel

    View full-size slide

  123. Bonus 2: HTML Präsentationen mit reveal.js
    14-reveal.js
    git clone
    [email protected]:arcSummit2017/examples.git

    View full-size slide

  124. Bonus 2: HTML Präsentationen mit reveal.js
    14-reveal.js

    View full-size slide

  125. docToolchain

    View full-size slide

  126. Danke!
    Ralf D. Müller
    @RalfDMüller
    https://rdmueller.github.io
    @docToolchain
    Gernot Starke
    @GernotStarke
    http://arc42.org/
    @arc42Tipps
    Clipart: presentermedia.com, licenced to [email protected]

    View full-size slide