Motivation
Today, the great importance of software documentation can be met with better state-of-the-art environments than Word or Confluence.
With a lightweight markup language—here AsciiDoc—the documents can be created and edited in any plain text editor. All contents and configurations remain fully readable and editable, without the need for idiosyncratic WYSIWYG applications or wiki platforms.
Software developers appreciate the proximity between program code and documentation as well as the ability to place the raw documents directly under version control. Readers from all target groups appreciate the professional, uniform, and well-maintained appearance of such a generated documentation structure.
Software documentation marked up for excellence is achieved by a holistic approach of a) a lightweight markup language, b) a documentation generator, and c) easy-to-implement organizational measures—which is exactly what you will learn in this workshop.
Program
The focus is on learning and practicing AsciiDoc as a lightweight markup language and Antora as the perfectly matching documentation generator. You will experience how selected diagram types can be generated from textual descriptions and how the appearance of entire documentation structures can be adapted centrally. All this is accompanied by informative explanations of the organizational who, how and what of software documentation.
- Day 1 | AsciiDoc
- importance and types of software documentation
- Docs as Code as a sustainable alternative to Word and Confluence
- AsciiDoc as a lightweight markup language
- text structuring and formatting
- classic and special documentation modules
- embedding code snippets and other documents
- Diagrams as Code as a textual alternative to “box shifting”
- outlook on documentation templates and automatic verification of architecture specifications through executable documentation
- Day 2 | Antora
- introduction to Antora’s main concepts:
- site
- component
- module
- version
- playbook
- structuring documentation into modules and components
- central customization of the look & feel and navigation
- integration with version control systems
- brief insight into the main alternative reStructuredText / Sphinx (mainly for Python projects)
- introduction to Antora’s main concepts:
Course Objectives
This two-day workshop will certainly help to clarify software documentation, provide new ideas, and open previously unknown doors. You will learn why previous attempts to document your own software architecture may only have worked in the short term, at best. Through many hands-on practical examples, you will gain an overview of the impressive possibilities offered by a docs-as-code and diagrams-as-code approach.
Target Groups
- all people working in the software area (developers, architects, project and product managers, department and team leaders, decision-makers, etc.)
Instructor
Christian Heitzmann is a Java-, Python- and Spring-certified software developer with a CAS in Machine Learning and owner of SimplexaCode in Lucerne. He has been developing software for over 20 years and has been teaching classes and courses for over 12 years in the areas of Java and Python programming, mathematics, and algorithms. As a technical writer, he documents software architectures for companies and regularly writes articles for IT journals.
Shortlink to this page: link.simplexacode.ch/mzg92024.03