Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Writing docs in your IDE – an AsciiDoc primer

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.

Alexander Schwartz

October 22, 2020
Tweet

More Decks by Alexander Schwartz

Other Decks in Programming

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
    [email protected]
    @ahus1de
    © msg | October 2020 | Writing docs in your IDE – an AsciiDoc primer | Alexander Schwartz 20

    View Slide