Dev-Docs @ CNCF End User SIG

this is only a small excerpt from my other talks

Transcript

1. Docs-as-Code@DB-Systel 05.08.2021 | Ralf D. Müller
2. 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
3. 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
4. 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
5. 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
6. 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
7. arc42 DB Systel GmbH | Ralf D. Müller | JUG CH | 13.04.2021 7
8. 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
9. 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
10. Diagrams.net (formerly known as draw.io) DB Systel GmbH | Ralf D. Müller | JUG CH | 13.04.2021 10
11. 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
12. 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
13. Basic Docs-as-Code with AsciiDoc & docToolchain