Slide 1

Slide 1 text

Docs-as-Code@DB-Systel 05.08.2021 | Ralf D. Müller

Slide 2

Slide 2 text

Docs-as-Code@DB-Sytel What do we do not as everyone else? AsciiDoc as Markup with great IntelliJ Support arc42 as Template for Solution Architecture diagrams.net with IDE Plugins docToolchain DB Systel GmbH | Ralf D. Müller | @RalfDMueller 2

Slide 3

Slide 3 text

Markdown Great Standard for easy Markup 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 DB Systel GmbH | Ralf D. Müller | @RalfDMueller 3

Slide 4

Slide 4 text

Markdown We need another flavour, but which one? •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 DB Systel GmbH | Ralf D. Müller | @RalfDMueller 4

Slide 5

Slide 5 text

DB Systel GmbH | Ralf D. Müller | @RalfDMueller 5 :::note The content and title *can* include markdown. ::: :::tip You can specify an optional title Heads up! Here's a pro-tip. ::: :::info Useful information. ::: :::caution Warning! You better pay attention! ::: :::danger Danger danger, mayday! ::: ::: tip This is a tip ::: ::: warning This is a warning ::: ::: danger This is a dangerous warning ::: ::: details This is a details block, which does not work in IE / Edge ::: https://v1.vuepress.vuejs.org/guide/markdown.html#custom-containers https://v2.docusaurus.io/docs/2.0.0-alpha.70/markdown-features > [!NOTE] > Information the user should > notice even if skimming. > [!TIP] > Optional information to help > a user be more successful. > [!IMPORTANT] > Essential information required > for user success. > [!CAUTION] > Negative potential consequences > of an action. > [!WARNING] > Dangerous certain consequences > of an action. https://docs.microsoft.com/de-de/contribute/markdown-reference

Slide 6

Slide 6 text

AsciiDoc / Asciidoctor Powerful syntax for tech-docs Written in Ruby Wrapped with jRuby to run on the JVM Transpiled to JavaScript via Opal => No Flavours DB Systel GmbH | Ralf D. Müller | @RalfDMueller 6

Slide 7

Slide 7 text

arc42 DB Systel GmbH | Ralf D. Müller | JUG CH | 13.04.2021 7

Slide 8

Slide 8 text

Architecture with Docs-as-Code ‒ How do I write System-Documentation? Dr. Peter Hruschka http://www.peterhruschka.eu/ Dr. Gernot Starke http://gernotstarke.de/ http://arc42.org/ DB Systel GmbH | Ralf D. Müller | JUG CH | 13.04.2021 8

Slide 9

Slide 9 text

arc42 … … is _the_ Standard-Template in Germany … is available in German, English, Spanish, Russian & Italian … is available in > 9 Formats (.adoc, .docx, .rst, .md, .tex …) … gives your docs a common Struktur … is available with and without Helpcontent Content | Motivation | Form … helps to document the right aspects in the right way DB Systel GmbH | Ralf D. Müller | JUG CH | 13.04.2021 9

Slide 10

Slide 10 text

Diagrams.net (formerly known as draw.io) DB Systel GmbH | Ralf D. Müller | JUG CH | 13.04.2021 10

Slide 11

Slide 11 text

Diagrams.net (formerly known as draw.io) DB Systel GmbH | Ralf D. Müller | JUG CH | 13.04.2021 11 PNG-Diagramm … Meta-Data

Slide 12

Slide 12 text

asciidoctor your solution architecture documentation pdf plugin diagram plugin plantUML read PDF generate PDF HTML5 generate HTML arc42 asciidoc template is derived from Basic Docs-as-Code with AsciiDoc

Slide 13

Slide 13 text

Basic Docs-as-Code with AsciiDoc & docToolchain

Slide 14

Slide 14 text

No content