Documentation for users with AsciiDoc and Antora

Documentation for a software project is essential for users, administrator and developers alike: Users need to find the right tutorials, reference documentation and answers to their questions, administrators need to know how to install and operate the software, while developers need other documents to get started contributing, and share concepts and architectures for fellow contributors.
The tool Antora simplifies the process by creating documentation websites from AsciiDoc sources stored in Git repositories. Users can browse the generated website and select the version matching the software they use. Navigation outlines, search and cross-references between pages allow users to find answers to their questions. Several open-source software projects like Camel, Debezium and Couchbase use this solution.
For developers it is normal to develop software in collaboration using their IDE and a version control system like Git. The same type of collaboration is possible when all documentation is versioned in a markup-format like AsciiDoc.
This talk presents the basics of an Antora setup and walks through all the steps from editing content in the IDE to updating the documentation site using continuous integration and delivery.

Transcript

1. Documentation for users with AsciiDoc and Antora Alexander Schwartz, Principal Software Engineer @ Red Hat Devoxx France | 2024-04-17
2. 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
3. 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
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“
5. 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
6. 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/
7. 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
8. 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. 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
10. 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
11. 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.
12. 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. ----
13. 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
14. 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 |===
15. 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.
16. 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
17. • 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/
18. 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
19. 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 … …
20. 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
21. 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)
22. 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)
23. 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)
24. 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/
25. 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!
26. 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
27. 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
28. 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
29. 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