Docs-as-code: An AsciiDoc primer

Slide 1

Slide 1 text

Docs-as-code – an AsciiDoc primer Alexander Schwartz, Principal IT Consultant DevConf.US 2021 – 03 September 2021

Slide 2

Slide 2 text

© msg | September 2021 | Docs-as-Code – an AsciiDoc primer | Alexander Schwartz 2 Writing docs in your IDE – an AsciiDoc primer Motivation 1. AsciiDoc as the Language 2. Demo AsciiDoc Syntax and Ecosystem 3. Summary 4.

Slide 3

Slide 3 text

Slide 4

Slide 4 text

Tool + – Office-Suite Wiki © msg | September 2021 | Docs-as-Code – an AsciiDoc primer | Alexander Schwartz 4 What do you use to write your docs? Motivation

Slide 5

Slide 5 text

© msg | September 2021 | Docs-as-Code – an AsciiDoc primer | Alexander Schwartz 5 What to aim for in a Continuous Integration/Delivery setup Motivation Code Snippets Publish result (to website) Printable Documentation Track Changes Search Documentation De-Duplication and Re-Use Text Code Fragments APIs Diagrams Tests Share Merge

Slide 6

Slide 6 text

6 Writing docs in your IDE – an AsciiDoc primer © msg | September 2021 | Docs-as-Code – an AsciiDoc primer | Alexander Schwartz Motivation 1. AsciiDoc as the Language 2. Demo AsciiDoc Syntax and Ecosystem 3. Summary 4.

Slide 7

Slide 7 text

© msg | September 2021 | Docs-as-Code – an AsciiDoc primer | Alexander Schwartz 7 AsciiDoc is the language, Asciidoctor is one toolchain Asciidoctor https://asciidoctor.org/ AsciiDoc • friction-less writing using plain text • feature-rich syntax for technical documentation • 15 years alive and kicking • standardization started in 2020 at Eclipse Foundation Asciidoctor • toolchain to create HTML and PDF from AsciiDoc files • OpenSource implementation • runs on Java, Ruby and JavaScript runtimes • can be integrated in a Maven build using plugins AsciiDoc Eclipse Working Group

Slide 8

Slide 8 text

• stay focused and don’t switch apps • collaborate using version control • IntelliJ AsciiDoc plugin provides Antora and AsciiDoc support © msg | September 2021 | Docs-as-Code – an AsciiDoc primer | Alexander Schwartz 8 Writing in the IDE List of editors: https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/

Slide 9

Slide 9 text

IDE support is available as plugins for all major IDEs, for example: • Eclipse IDE • IntelliJ IDEA (including WebStorm, RubyMine, PyCharm, GoLand, etc.) • Atom • Visual Studio Code • Brackets Live preview is available: • via Browser extensions for Firefox, Opera and Chrome Stand-alone editor is available: • Asciidoc FX © msg | September 2021 | Docs-as-Code – an AsciiDoc primer | Alexander Schwartz 9 IDE support for AsciiDoc Source: https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/

Slide 10

Slide 10 text

© msg | September 2021 | Docs-as-Code – an AsciiDoc primer | Alexander Schwartz 10 Writing docs in your IDE – an AsciiDoc primer Motivation 1. AsciiDoc as the Language 2. Demo AsciiDoc Syntax and Ecosystem 3. Summary 4.

Slide 11

Slide 11 text

Slide 12

Slide 12 text

Slide 13

Slide 13 text

Slide 14

Slide 14 text

Slide 15

Slide 15 text

Slide 16

Slide 16 text

Slide 17

Slide 17 text

Slide 18

Slide 18 text

© msg | September 2021 | Docs-as-Code – an AsciiDoc primer | Alexander Schwartz 18 Writing docs in your IDE – an AsciiDoc primer Motivation 1. AsciiDoc as the Language 2. Demo AsciiDoc Syntax and Ecosystem 3. Summary 4.

Slide 19

Slide 19 text

Why to use AsciiDoc Up-to-date and correct content by collaboration as a team via version control system Consistent content across different documents by publishing to various formats, de-duplication and re-use Focusing to deliver new features in line with documentation by automation of document delivery © msg | September 2021 | Docs-as-Code – an AsciiDoc primer | Alexander Schwartz AsciiDoc promotes collaboration, de-duplication, and automated publishing 19

Slide 20

Slide 20 text

© msg | September 2021 | Docs-as-Code – an AsciiDoc primer | Alexander Schwartz 20 AsciiDoc is the language, Asciidoctor is one toolchain Asciidoctor https://asciidoctor.org/ AsciiDoc • friction-less writing using plain text • feature-rich syntax for technical documentation • 15 years alive and kicking • standardization started in 2020 at Eclipse Foundation Asciidoctor • toolchain to create HTML and PDF from AsciiDoc files • OpenSource implementation • runs on Java, Ruby and JavaScript runtimes • can be integrated in a Maven build using plugins AsciiDoc Eclipse Working Group

Slide 21

Slide 21 text

AsciiDoc Working Group @ Eclipse https://asciidoc-wg.eclipse.org/ Asciidoctor https://asciidoctor.org/ PlantUML http://plantuml.com/ https://real-world-plantuml.com/ docToolchain https://doctoolchain.github.io/docToolchain/ © msg | September 2021 | Docs-as-Code – an AsciiDoc primer | Alexander Schwartz 21 Links @ahus1de Asciidoctor PDF.js https://github.com/Mogztter/asciidoctor-pdf.js Antora https://antora.org/ Video, Slides and Examples https://www.ahus1.de/post/asciidoctor-intro-and-deep-dive

Slide 22

Slide 22 text

msg systems ag Robert-Bürkle-Straße 1 85737 Ismaning Germany value – inspired by people Contact Alexander Schwartz Principal IT Consultant +49 171 5625767 [email protected] @ahus1de © msg | September 2021 | Docs-as-Code – an AsciiDoc primer | Alexander Schwartz 22