Tweet
Tweet

Slide 1

Slide 1 text

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

Slide 2

Slide 2 text

© 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.

Slide 3

Slide 3 text

© 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

Slide 4

Slide 4 text

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

Slide 5

Slide 5 text

© 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

Slide 6

Slide 6 text

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.

Slide 7

Slide 7 text

© 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

Slide 8

Slide 8 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 | 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/

Slide 9

Slide 9 text

© 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.

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

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

Slide 13

Slide 13 text

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

Slide 14

Slide 14 text

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

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

© 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.

Slide 17

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

Slide 18

Slide 18 text

© 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

Slide 19

Slide 19 text

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

Slide 20

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