Documentation for users with AsciiDoc and Antora Alexander Schwartz, Principal Software Engineer @ Red Hat Devoxx France | 2024-04-17

CC BY-NC-SA 4.0 | April 2024 | Documentation for users​ with AsciiDoc and Antora | Alexander Schwartz 2 Documentation for users with AsciiDoc and Antora How users search for information 1 How AsciiDoc and Antora help 2 Setting up Antora 3 Empower your users! 4

CC BY-NC-SA 4.0 | April 2024 | Documentation for users​ with AsciiDoc and Antora | Alexander Schwartz 3 Documentation for users with AsciiDoc and Antora How users search for information 1 How AsciiDoc and Antora help 2 Setting up Antora 3 Empower your users! 4

CC BY-NC-SA 4.0 | April 2024 | Documentation for users​ with AsciiDoc and Antora | Alexander Schwartz How users search for information 4 How users search: Chasing for answers • Search engine: End up somewhere in the online docs • Click where they suspectthe right answer • Done, when they find an answer that is „good enough“

CC BY-NC-SA 4.0 | April 2024 | Documentation for users​ with AsciiDoc and Antora | Alexander Schwartz How users search for information 5 The helpful documentationsite 1. Recurring structures 2. Contents that are simple to scan 3. Search within the site 4. Navigation

CC BY-NC-SA 4.0 | April 2024 | Documentation for users​ with AsciiDoc and Antora | Alexander Schwartz How users search for information 6 Every Page is Page One (EPPO) Build a page so users can starttheir journey on any page: • Context at the beginning • Self-contained content on each page • Focused on a specific topic • Link to the prerequisites More on: • https://everypageispageone.com/the-book/

CC BY-NC-SA 4.0 | April 2024 | Documentation for users​ with AsciiDoc and Antora | Alexander Schwartz 7 Documentation for users with AsciiDoc and Antora How users search for information 1 How AsciiDoc and Antora help 3 Setting up Antora 2 Empower your users! 4

CC BY-NC-SA 4.0 | April 2024 | Documentation for users​ with AsciiDoc and Antora | Alexander Schwartz 8 Empower your users with documentation so they get their work done Why AsciiDoc and Antora • Searchable and topic-based • Navigation and cross references • Grouped by version and component

9 Why AsciiDoc and Antora CC BY-NC-SA 4.0 | April 2024 | Documentation for users​ with AsciiDoc and Antora | Alexander Schwartz Antora provides publishing tools and documentation structure • Structures documentation into components and modules • Collects AsciiDoc content from multiple Git repositories and branches • Converts AsciiDoc content to HTML output • Merges HTML output with UI theme to create a static site Key benefits: • Fast conversion (Node.js with minimal dependencies) • Modular and extendible

CC BY-NC-SA 4.0 | April 2024 | Documentation for users​ with AsciiDoc and Antora | Alexander Schwartz Why AsciiDoc and Antora 10 AsciiDoc is the language, Asciidoctor is a toolchain 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 other outputs from AsciiDoc • OpenSource • runs on Java, Ruby and JavaScript runtimes • powers Antora’s AsciiDoc to HTML conversion

CC BY-NC-SA 4.0 | April 2024 | Documentation for users​ with AsciiDoc and Antora | Alexander Schwartz 11 Demo AsciiDoc Syntax and Ecosystem AsciiDoc: Texts and Lists Each sentence should be in a separate line. Every blank line creates a new paragraph. You can write *bold* text. _Italic_ works as well text. Lists . work . with . dots to make them numbered and * asterisks * to * make bullet points.

CC BY-NC-SA 4.0 | April 2024 | Documentation for users​ with AsciiDoc and Antora | Alexander Schwartz 12 Demo AsciiDoc Syntax and Ecosystem AsciiDoc: Paragraphs and admonitions [IMPORTANT] -- You can mark a paragraph to be important. -- TIP: There is also the shorter one-line- syntax. ==== This is an example block. Use it to provide examples to your users. ==== ---- This is a listing. You can provide syntax highlighting for XML/Java etc. here. ----

CC BY-NC-SA 4.0 | April 2024 | Documentation for users​ with AsciiDoc and Antora | Alexander Schwartz 13 Demo AsciiDoc Syntax and Ecosystem AsciiDoc: Include source code examples .Standard include [source,java] ---- include::Example.java[] ---- :icons: font .Pick a block with callout [source,java,indent=0] ---- include::Example.java[tag=sop] ---- <1> this is your first line of Java

CC BY-NC-SA 4.0 | April 2024 | Documentation for users​ with AsciiDoc and Antora | Alexander Schwartz 14 Demo AsciiDoc Syntax and Ecosystem AsciiDoc: Tables Tables are blocks, `|===` marks their beginning and end. .Table title [cols="1,1,3a,1"] |=== |H1 |H2 |H3 |H4 |Cell 1 |Cell 2 |Formatting *of words* works like in _before_ if you switch the column or cell to AsciiDoc format. |Cell 4 |===

CC BY-NC-SA 4.0 | April 2024 | Documentation for users​ with AsciiDoc and Antora | Alexander Schwartz 15 Demo AsciiDoc Syntax and Ecosystem AsciiDoc: Pictures Images can be in-line and as blocks. An image:file.svg[pdfwidth=3cm] image in- line. An image with a caption: .This is an image image::file.svg[] For schematic drawings prefer to use SVG images for best results on the Web and in PDFs.

CC BY-NC-SA 4.0 | April 2024 | Documentation for users with AsciiDoc and Antora | Alexander Schwartz 16 Demo AsciiDoc Syntax and Ecosystem AsciiDoc: Diagrams with PlantUML To store diagrams as text, have a look at PlantUML: .Diagrams can have a caption as well. plantuml::showcase_swimlanes.puml[swimlanes,svg] @startuml skinparam shadowing false |Component with Web-UI| start :User opens web page; :Forward to authentication; |#AntiqueWhite|Authentication| :Authenticate with user name\nand password; :Forward to Web-UI; |Component with Web-UI| :Open Web-UI; stop @enduml

• stay focused and don’t switch apps • collaborate using version control • IntelliJ AsciiDoc plugin provides Antora and AsciiDoc support CC BY-NC-SA 4.0 | April 2024 | Documentation for users​ with AsciiDoc and Antora | Alexander Schwartz 17 Writing in the IDE Why AsciiDoc and Antora List of editors: https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/

CC BY-NC-SA 4.0 | April 2024 | Documentation for users​ with AsciiDoc and Antora | Alexander Schwartz 18 Documentation for users with AsciiDoc and Antora How users search for information 1 How AsciiDoc and Antora help 2 Setting up Antora 3 Empower your users! 4

CC BY-NC-SA 4.0 | April 2024 | Documentation for users​ with AsciiDoc and Antora | Alexander Schwartz Setting up Antora 19 Antora: Structure • Multiple independent components • Each component is identified by name and version • One navigation per component • Each component can have multiple modules • Each module has pre-defined families for pages, images, examples, attachments and partials (content snippets to be included in multiple places) Advanced feature: A component can be distributed across multiple folders, branches and repositories Component images pages partials Module … …

Git Repo CC BY-NC-SA 4.0 | April 2024 | Documentation for users​ with AsciiDoc and Antora | Alexander Schwartz Setting up Antora 20 Antora: Process What the user does: 1. Run Antora What Antora does: 1. Load Antora playbook with list of repositories and branches 2. Clone Git repositories 3. Create HTML output from AsciiDoc 4. Merge with UI theme and UI customizations 5. Optional: Create search index 6. Create output folder with static site Playbook Git Repo Antora Static Site UI Theme

CC BY-NC-SA 4.0 | April 2024 | Documentation for users​ with AsciiDoc and Antora | Alexander Schwartz 21 Antora: Roles Setting up Antora Role Professional Skills Technical Skills Author Structuring and Writing • Git (to collaborate with other authors) • AsciiDoc (to create content)

CC BY-NC-SA 4.0 | April 2024 | Documentation for users​ with AsciiDoc and Antora | Alexander Schwartz 22 Antora: Roles Setting up Antora Role Professional Skills Technical Skills Author Structuring and Writing • Git (to collaborate with other authors) • AsciiDoc (to create content) Docu Ops Automation and Infrastructure • Git (for initial setup) • YAML (for configuration) • package.json(for version management) • Continuous Integration (for automation)

CC BY-NC-SA 4.0 | April 2024 | Documentation for users​ with AsciiDoc and Antora | Alexander Schwartz 23 Antora: Roles Setting up Antora Role Professional Skills Technical Skills Author Structuring and Writing • Git (to collaborate with other authors) • AsciiDoc (to create content) Docu Ops Automation and Infrastructure • Git (for initial setup) • YAML (for configuration) • package.json(for version management) • Continuous Integration (for automation) Web Developer Web Site Creation • HTML/CSS (to customize Antora theme)

Author: 1. Create first component folder structure 2. Create antora.ymland give the component a name and version 3. Create index.adoc in pages 4. Create navigation entries in nav.adoc and add it to antora.yml Docu Ops: 1. Install Antora (either via npmCLI or package.json file) 2. Create playbook to generate local preview site for authors 3. Create playbook to publish the site on the Internet Web Developer: 1. Copy the existing UI theme (or create your own) 2. Add UI customizations via supplemental files CC BY-NC-SA 4.0 | April 2024 | Documentation for users​ with AsciiDoc and Antora | Alexander Schwartz 24 Antora: First Steps Setting up Antora my-component ├─ antora.yml └─ modules ├─ ROOT │ ├─ attachments │ ├─ examples │ ├─ images │ ├─ pages │ │ └─ index.adoc │ ├─ partials │ └─ nav.adoc └─ a-named-module └─ pages Quick Start Guide: https://docs.antora.org/antora/3.1/install-and-run-quickstart/

CC BY-NC-SA 4.0 | April 2024 | Documentation for users​ with AsciiDoc and Antora | Alexander Schwartz 25 Setting up Antora Demo time See how this works using the IntelliJ AsciiDoc plugin!

CC BY-NC-SA 4.0 | April 2024 | Documentation for users​ with AsciiDoc and Antora | Alexander Schwartz 26 Documentation for users with AsciiDoc and Antora How users search for information 1 How AsciiDoc and Antora help 2 Setting up Antora 3 Empower your users! 4

Empower your users! Keep your content up-to-date using collaboration as a team using version control Keep your content consistent by handling component versions and de-duplication of content Publish new features for software and documentation in sync using CI/CD tools to automate publishing CC BY-NC-SA 4.0 | April 2024 | Documentation for users​ with AsciiDoc and Antora | Alexander Schwartz Empower your users with documentation so they get their work done 27

AsciiDoc https://asciidoc.org Asciidoctor https://asciidoctor.org IntelliJ AsciiDoc Plugin https://ahus1.de/post/technical-writing-udemy Links CC BY-NC-SA 4.0 | April 2024 | Documentation for users​ with AsciiDoc and Antora | Alexander Schwartz 28 @ahus1de Antora https://antora.org/ https://www.ahus1.de/post/documentation-site-antora Videos, slides and examples https://www.ahus1.de/post/asciidoctor-intro-and-deep-dive https://www.ahus1.de/post/cdc-antora-live @ahus1@fosstodon.org

Contact Alexander Schwartz Principal Software Engineer alexander.schwartz@gmx.net https://www.ahus1.de @ahus1de @ahus1@fosstodon.org CC BY-NC-SA 4.0 | April 2024 | Documentation for users​ with AsciiDoc and Antora | Alexander Schwartz 29