Docs-as-code: An AsciiDoc primer

Follow the documentation-as-code approach: Write documentation in your IDE, collaborate with other developers and writers using version control and let a continuous integration server scrutinize and publish your docs.

AsciiDoc is a lightweight markup language that translates for example to HTML and PDF. In your development environment, an IDE plugin provides editor support and preview pane.

After a short introduction to AsciiDoc this workshop shows how to edit and structure content in a development environment. Live examples show how to work with the AsciiDoc in the IDE and the build process.

Participants are invited to join via a web-based collaborative editor (preferred) or working locally in their IDEs (IntelliJ or Eclipse). To make full use of the collaboration during the workshop, we ask participants to download and install the Zoom client for meetings. For the web-based collaborative editor Google Chrome or Mozilla Firefox work best.

Transcript

1. Docs-as-code – an AsciiDoc primer Alexander Schwartz, Principal IT Consultant DevConf.US 2021 – 03 September 2021
2. © 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.
3. © msg | September 2021 | Docs-as-Code – an AsciiDoc primer | Alexander Schwartz 3 What do you use to write your docs? Motivation Tool + – Office-Suite
4. 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
5. © 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
6. 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.
7. © 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
8. • 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/
9. 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/
10. © 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.
11. © msg | September 2021 | Docs-as-Code – an AsciiDoc primer | Alexander Schwartz Web Editor with Live Preview Try out AsciiDoc for yourself! 11 Scratch List Source Code Preview
12. © msg | September 2021 | Docs-as-Code – an AsciiDoc primer | Alexander Schwartz Formatting basic Text Writing and Structuring AsciiDoc 12
13. © msg | September 2021 | Docs-as-Code – an AsciiDoc primer | Alexander Schwartz Formatting Paragraphs Writing and Structuring AsciiDoc 13
14. | | | | | | | © msg | September 2021 | Docs-as-Code – an AsciiDoc primer | Alexander Schwartz Formatting Tables Writing and Structuring AsciiDoc 14
15. © msg | September 2021 | Docs-as-Code – an AsciiDoc primer | Alexander Schwartz Adding Images Writing and Structuring AsciiDoc 15
16. © msg | September 2021 | Docs-as-Code – an AsciiDoc primer | Alexander Schwartz Using PlantUML for diagrams Writing and Structuring AsciiDoc 16
17. © msg | September 2021 | Docs-as-Code – an AsciiDoc primer | Alexander Schwartz Including source code snippets Writing and Structuring AsciiDoc 17
18. © 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.
19. 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
20. © 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
21. 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
22. 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 alexander.schwartz@msg.group @ahus1de © msg | September 2021 | Docs-as-Code – an AsciiDoc primer | Alexander Schwartz 22