Admin-Dokumentation mit AsciiDoc

RMF it-support@rmf.berlin

Weniger schlecht dokumentieren

Die Welt wird aber sicher kein schlechterer Ort dadurch, dass Sie […] die allgemeine Unzulänglichkeit von fast allem anerkennen und sich damit begnügen Code zu schreiben, den Sie selbst auch in sechs Monaten noch verstehen können.

Weniger Schlecht programmieren
— Kathrin Passig & Johannes Jander

[…](Dokumentationen) sind kein dekoratives Element, das man ganz zum Schluss anbringt, wenn die eigentliche Arbeit getan ist. Bei Menschen von durchschnittlicher (lies: nicht vorhandener) Selbstdisziplin und Willenskraft findet dieser letzte Schritt sowieso nie statt. Und selbst wenn man sich dazu durchringt, hat man die Hälfte der Überlegungen, die einen […] (in dem Prozess) beschäftigten schon wieder vergessen.

— ebenda

Was Sie erwartet …

Weniger schlecht dokumentieren
Was Sie erwartet …
Dokumentenmanagement
Dokumentation – Zielgruppen
Anforderungen
AsciiDoc und AsciiDoctor
VS Codium / VS Code einrichten
Hilfreiche Tools
Live-Demo
Arbeitsstruktur
AsciiDoc Document Structure
Haupt- und Filialdokumente
Corporate Design – AsciiDoc Themes
Hilfreiche Videos | Links
Fragen / Anmerkungen

Dokumentenmanagement

Dokumentenmanagementsystem

Umfangreiche Dokumentation im Unternehmen
- Prozesse und Verfahren
- Handbücher und Anweisungen für Mitarbeitende der verschiedenen Abteilungen
- DSGVO
- IT-Grundschutz (BSI)
IT-Dokumentation als Teil der Geschäftsprozesse
Dokumentation als Wissenserhalt und Wissensweitergabe
- unabhängig von einzelnen Personen

Dokumentation – Zielgruppen

intern
- Dokumentation der eigenen Arbeit
- Admin-Kolleg:innen
- Entwickler-Kolleg:innen
extern
- Geschäftsführung
- Leitungskräfte
- Endanwender:innen
- externe Dienstleister

Anforderungen

Hauptdokument mit beliebigen Filialdokumenten
Filialdokument auch als Einzel-PDF mit gleichem Layout
nicht-proprietäres Dateiformat
aber auch Ausgabe als Word-Dokument erwartet
unabhängig vom Betriebssystem

LaTeX
Markdown
AsciiDoc
…

… Anforderungen

Auch von Nicht-Programmierer:innen zu pflegen
Import code / code-snippets on the fly
gemeinsames Arbeiten an (Teil-)Dokumenten
Versionskontrolle
Aktueller Stand der Dokumentation mind. in der Firmen-Cloud (PDF)
Firmeninternes Wiki

Ausgabe als
- PDF – auch als Einzel-Dokumente
- Word *.docx
- markdown strict → Import in BookStack (Wiki)

AsciiDoc und AsciiDoctor

AsciiDoc – ist die Sprache

Auszeichnungssprache ähnlich wie Markdown asciidoc.org/.
Großer Funktionsumfang
Seit über 15 Jahren verfügbar und weiterentwickelt
Standardisierung seit 2020 bei der Eclipse Foundation (www.eclipse.org/org/workinggroups/asciidoc-charter.php)

AsciiDoctor – ist das Werkzeug

»a fast text processor and publishing toolchain for converting AsciiDoc to HTML5, DocBook and more« asciidoctor.org/ und docs.asciidoctor.org/
Open Source
Läuft auch in Java, Ruby und JavaScript

Ausgabe in weitere Formate wie EPUB, HTML, DocBook, Manpage via 'pandoc' usw. möglich

Web-Links Dokumentation zu AsciiDoc/AsciiDoctor

AsciiDoctor Documentation

AsciiDoc Syntax Quick Reference

AsciiDoctor PDF Theming Guide

AsciiDoctor PDF Default / Base Themes

… Web-Links Dokumentation zu AsciiDoc/AsciiDoctor

Antora (Alexander Schwartz): The multi-repository documentation site generator for tech writers who ♥︎ writing in AsciiDoc. https://antora.org/

Siehe auch https://docs.antora.org/antora/latest/

VS Codium / VS Code einrichten

VSCodium: Free/Libre Open Source Software Binaries of VS Code.
VSCodium is a community-driven, freely-licensed binary distribution of Microsoft’s editor VS Code.

VS Code: Visual Studio Code is licensed under this not-FLOSS license and contains telemetry/tracking.

Empfehlenswerte PlugIns

VSCodium | Open VSX Registry

Visual Studio | Marketplace

AsciiDoc
AsciiDoc Slides
Better Comments
Bookmarks
Code Spell Checker
German – Code Spell Checker
German Language Pack for Visual Studio Code

… Empfehlenswerte PlugIns

PlantUML
PlantUML Syntax
Project Manager
Todo Tree
vscode-icons

Tasks einrichten

Mit Tasks können sich wiederholende Aufgaben leicht automatisiert werden.

Im Projekt-Verzeichnis ein Verzeichnis .vscode anlegen und darin in tasks.json die gewünschten Aufgaben definieren.

Hier dieses AsciiDoc-Dokument in HTML5 wandeln und HTML-Datei im Browser öffnen.

Slides asciidoc → html5

{
  // See https://go.microsoft.com/fwlink/?LinkId=733558
  // for the documentation about the tasks.json format
  "version": "2.0.0",
  "tasks": [
    {
      "label": "AsciiDocSlide",
      "type": "shell",
      "command": "npx asciidoctor-revealjs ${file} && open ${relativeFileDirname}/${fileBasenameNoExtension}.html",
      "problemMatcher": [],
      "group": {
        "kind": "build",
        "isDefault": true
      }
    },
    {
      "label": "ascidoctor-pdf",
      "type": "shell",
      "command": "workbench.action.files.save",
      "type": "shell",
      "command": "asciidoctor-pdf -a pdf-themesdir=/Users/webmaster/Documents/99_Vortrag/FrosCon2023/ressources/themes/ -a pdf-theme=froscon -a pdf-fontsdir=/Users/webmaster/Documents/99_Vortrag/FrosCon2023/ressources/fonts/ ${file} && open ${relativeFileDirname}/${fileBasenameNoExtension}.pdf",
      "problemMatcher": [],
      "group": {
        "kind": "build",
        "isDefault": true
      }
    },

Hilfreiche Tools

Obsidian – die private und flexible App für Markdown-Notizen, die sich an Ihre Denkweise anpasst.
Basierend auf der Zettelkasten-Idee von Niklas Luhmann; jede Notiz kann mit jeder beliebigen anderen Notiz verlinkt werden.
Clipboard-Manager
BookStack Simple & Free Wiki Software
BookStack is a simple, self-hosted, easy-to-use platform for organising and storing information.

… BookStack Wiki

Diffenrenziertes Rollen- und Rechtesystem.
- Admins
- Leitungskräfte
- Sachbearbeitung
- oä.

Informationsstruktur:
- Regale
  - Bücher
    Kapitel
    Seiten

Live-Demo

Diese Slides und die Dateien der Live-Demo sind bei github zu finden. github.com:rmfberlin/FrosCon2023.git

Arbeitsstruktur

ein zentrales Verzeichnis asciidoc/ressources, das für alle AsciiDoc-Projekte die benötigten Templates, Fonts, Images usw. enthält (hier in der Demo im Projektverzeichnis)
- resources/fonts
- resources/img
- resources/themes
im Projekt-Verzeichnis ein Verzeichnis ./vscode
- darin tasks.json mit den projektbezogenen Aufgaben
templates/ für projektbezogene Vorlagen
ggf. weitere Unterverzeichnisse

AsciiDoc Document Structure

= Document Title (Level 0)
// Header attribute

== Level 1 Section Title

=== Level 2 Section Title

==== Level 3 Section Title

===== Level 4 Section Title

====== Level 5 Section Title

== Another Level 1 Section Title

Document Header – Attributes

Im Kopf einer *.adoc-Datei können nach dem ersten = für den Dokumententitel Attribute gesetzt werden. Diese werden mit : eingeschlossen. Zum Beispiel

:docstatus: In Bearbeitung

Mit

 {docstatus}

wird der Inhalt/Wert des Attributes :docstatus: als "In Bearbeitung" ausgegeben.

Beispiel Document Header

:author: RMF
:email: it-support@rmf.berlin
:source-highlighter: rouge
:lang: DE
:icons: font
:doctype: book
:docstatus: Neufassung (edit)
// :docstatus: Aktiv
// :docstatus: Archiviert (inaktiv)
:asciidoc-file: 90-01-admin-doku.adoc
:docdate: 08.04.2020
:revnumber: 2.0.24
:revdate: {localdate}
:revremark: BookStack
:last-update-label: zuletzt geändert:
:table-caption: Tabelle
:toc-title: Inhalt
:toc: macro
:toclevels: 3
:sectnums:
:hide-uri-scheme:
:chapter-label: Kapitel
:hyphens:
:all-docs!:
:toc:
:appendix-caption: Anhang
:title-page:

Haupt- und Filialdokumente

Die Aufteilung in Einzeldokument dient der besseren Wartbarkeit und Revision der einzelnen Dokumentationen.
Ebenso können einzelne Dokumente herausgegeben werden,
- ohne die gesamte Dokumentation – die auch Sicherheitsinformationen enthält –
zur Verfügung stellen zu müssen.

… Haupt- und Filialdokumente

Jedes AsciiDoc-Dokument kann sowohl Haupt- als auch Filialdokument sein.
Filialdokumente werden über die Directive include::dateiname.art[tag=MyTag] in das Hauptdokument eingebunden.

Dabei können einzelne oder mehrere Abschnitte des Filialdokuments eingebunden werden.
Der jeweilige Abschnitt wird mit tag::MyTag und end::MyTag als Kommentarzeile eingeschlossen.
Kommentar entsprechend der Syntax der jeweiligen Quelldatei wie *.adoc. *.py, *.sh usw.

Umfangreiche Dokumente mit vielen Filialdokumenten

Bei mehreren Abschnitten müssen unterschiedliche Tags vergeben werden.
include::dateiname.adoc[tag=MyTag]
include::dateiname.adoc[tag=AnotherTag]

Im Document Header kann ein Attribute :all-docs: gesetzt werden.

Negiert wird dieses Attribute mit :all-docs!:

Darüber lassen sich Filialdokumente ein- bzw. ausschließen.

Quellcode wird wie folgt inkludiert:

 ifdef::all-docs[]
 [source, art]
 ----
  include::dateiname.art[tag=MyTag]
 ----
 endif::[]

Corporate Design – AsciiDoc Themes

Die Ausgabe des PDF bzw. des HTML lässt sich durch Themes-Anweisungen und entsprechende Fonts sowie Logo und Hintergründe dem gewünschten Corporate Design anpassen.

Asciidoctor PDF Theming Guide

github.com/asciidoctor/asciidoctor-pdf/blob/v1.5.0.beta.7/docs/theming-guide.adoc

AsciiDoctor PDF Default / Base Themes

github.com/asciidoctor/asciidoctor-pdf/tree/main/data/themes