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.

Developers in particular are convinced not only by the proximity of program code and documentation, but also by the ability to put the raw markup documents under version control and have the finished formatted documents be generated automatically via a build pipeline and be exported as various formats.

For anyone working in the software field, AsciiDoc is the language for effective software documentation, and its capabilities outshine any enterprise wiki.

Program

The focus is on learning and practicing AsciiDoc as a lightweight markup language as well as generating selected diagram types from textual descriptions. This is accompanied by informative explanations of the who, how and what of software documentation.

  • Day 1
    • 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

Course Objectives

This one-day workshop will certainly provide a lot of clarity regarding software documentation, deliver new ideas, and open previously unknown doors. You will learn why previous attempts to document your own software architecture have only worked in the short term at best. In just one day, you can get 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.

Software Documentation with AsciiDoc 1 Software Documentation with AsciiDoc 2

Shortlink to this page: link.simplexacode.ch/mzg92023.11