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

Dev-Docs @ CNCF End User SIG

Ralf D. Müller
August 05, 2021

Dev-Docs @ CNCF End User SIG

this is only a small excerpt from my other talks

Ralf D. Müller

August 05, 2021


  1. 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
  2. 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
  3. 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
  4. 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
  5. 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
  6. 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
  7. 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
  8. Diagrams.net (formerly known as draw.io) DB Systel GmbH | Ralf

    D. Müller | JUG CH | 13.04.2021 11 PNG-Diagramm <xml> … </xml> Meta-Data
  9. 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