Writing docs in your IDE – 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. Every commit to your version control system not only enhances your program, but also your architecture, developer or user documentation.

After a short introduction to AsciiDoc this talk 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.

Transcript

1. Writing docs in your IDE – an AsciiDoc primer
   Alexander Schwartz, Principal IT Consultant
   EclipseCon 2020 – 22 October 2020
   

   View Slide

2. © msg | October 2020 | Writing docs in your IDE – 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 | October 2020 | Writing docs in your IDE – 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 | October 2020 | Writing docs in your IDE – an AsciiDoc primer | Alexander Schwartz 4
   What do you use to write your docs?
   Motivation
   

   View Slide

5. © msg | October 2020 | Writing docs in your IDE – 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 | October 2020 | Writing docs in your IDE – an AsciiDoc primer | Alexander Schwartz
   Motivation
   1.
   AsciiDoc as the Language
   2.
   Demo AsciiDoc Syntax and Ecosystem
   3.
   Summary
   4.
   

   View Slide

7. © msg | October 2020 | Writing docs in your IDE – 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. 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 | October 2020 | Writing docs in your IDE – an AsciiDoc primer | Alexander Schwartz 8
   IDE support for AsciiDoc
   Source:
   https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/
   

   View Slide

9. © msg | October 2020 | Writing docs in your IDE – an AsciiDoc primer | Alexander Schwartz 9
   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

10. © msg | October 2020 | Writing docs in your IDE – an AsciiDoc primer | Alexander Schwartz
    Formatting basic Text
    Writing and Structuring AsciiDoc
    10
    

    View Slide

11. © msg | October 2020 | Writing docs in your IDE – an AsciiDoc primer | Alexander Schwartz
    Formatting Paragraphs
    Writing and Structuring AsciiDoc
    11
    

    View Slide

12. |
    |
    |
    |
    |
    |
    |
    © msg | October 2020 | Writing docs in your IDE – an AsciiDoc primer | Alexander Schwartz
    Formatting Tables
    Writing and Structuring AsciiDoc
    12
    

    View Slide

13. © msg | October 2020 | Writing docs in your IDE – an AsciiDoc primer | Alexander Schwartz
    Adding Images
    Writing and Structuring AsciiDoc
    13
    

    View Slide

14. © msg | October 2020 | Writing docs in your IDE – an AsciiDoc primer | Alexander Schwartz
    Using PlantUML for diagrams
    Writing and Structuring AsciiDoc
    14
    

    View Slide

15. © msg | October 2020 | Writing docs in your IDE – an AsciiDoc primer | Alexander Schwartz
    Including source code snippets
    Writing and Structuring AsciiDoc
    15
    

    View Slide

16. © msg | October 2020 | Writing docs in your IDE – an AsciiDoc primer | Alexander Schwartz 16
    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

17. 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 | October 2020 | Writing docs in your IDE – an AsciiDoc primer | Alexander Schwartz
    AsciiDoc promotes collaboration, de-duplication, and automated publishing
    17
    

    View Slide

18. © msg | October 2020 | Writing docs in your IDE – an AsciiDoc primer | Alexander Schwartz 18
    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

19. AsciiDoc Working Group @ Eclipse
    https://www.eclipse.org/lists/asciidoc-wg/
    Asciidoctor
    https://asciidoctor.org
    PlantUML
    http://plantuml.com/
    https://real-world-plantuml.com/
    docToolchain
    https://doctoolchain.github.io/docToolchain/
    © msg | October 2020 | Writing docs in your IDE – an AsciiDoc primer | Alexander Schwartz 19
    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

20. 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 | October 2020 | Writing docs in your IDE – an AsciiDoc primer | Alexander Schwartz 20
    

    View Slide