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
   

   View Slide

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.
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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.
   

   View Slide

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
   

   View Slide

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/
   

   View Slide

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/
   

   View Slide

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.
    

    View Slide

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
    

    View Slide

12. © msg | September 2021 | Docs-as-Code – an AsciiDoc primer | Alexander Schwartz
    Formatting basic Text
    Writing and Structuring AsciiDoc
    12
    

    View Slide

13. © msg | September 2021 | Docs-as-Code – an AsciiDoc primer | Alexander Schwartz
    Formatting Paragraphs
    Writing and Structuring AsciiDoc
    13
    

    View Slide

14. |
    |
    |
    |
    |
    |
    |
    © msg | September 2021 | Docs-as-Code – an AsciiDoc primer | Alexander Schwartz
    Formatting Tables
    Writing and Structuring AsciiDoc
    14
    

    View Slide

15. © msg | September 2021 | Docs-as-Code – an AsciiDoc primer | Alexander Schwartz
    Adding Images
    Writing and Structuring AsciiDoc
    15
    

    View Slide

16. © msg | September 2021 | Docs-as-Code – an AsciiDoc primer | Alexander Schwartz
    Using PlantUML for diagrams
    Writing and Structuring AsciiDoc
    16
    

    View Slide

17. © msg | September 2021 | Docs-as-Code – an AsciiDoc primer | Alexander Schwartz
    Including source code snippets
    Writing and Structuring AsciiDoc
    17
    

    View Slide

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.
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide