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
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.
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
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
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
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.
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
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/
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.
10. © msg | October 2020 | Writing docs in your IDE – an AsciiDoc primer | Alexander Schwartz Formatting basic Text Writing and Structuring AsciiDoc 10
11. © msg | October 2020 | Writing docs in your IDE – an AsciiDoc primer | Alexander Schwartz Formatting Paragraphs Writing and Structuring AsciiDoc 11
12. | | | | | | | © msg | October 2020 | Writing docs in your IDE – an AsciiDoc primer | Alexander Schwartz Formatting Tables Writing and Structuring AsciiDoc 12
13. © msg | October 2020 | Writing docs in your IDE – an AsciiDoc primer | Alexander Schwartz Adding Images Writing and Structuring AsciiDoc 13
14. © msg | October 2020 | Writing docs in your IDE – an AsciiDoc primer | Alexander Schwartz Using PlantUML for diagrams Writing and Structuring AsciiDoc 14
15. © msg | October 2020 | Writing docs in your IDE – an AsciiDoc primer | Alexander Schwartz Including source code snippets Writing and Structuring AsciiDoc 15
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.
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
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
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
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