Admin-Dokumentation mit AsciiDoc

Was Sie erwartet …

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

120

AsciiDoc – ist die Sprache

120

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

VS Codium / VS Code einrichten

100
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.

60
VS Code

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

Empfehlenswerte PlugIns

  • AsciiDoc

  • AsciiDoc Slides

  • Better Comments

  • Bookmarks

  • Code Spell Checker

  • German – Code Spell Checker

  • German Language Pack for Visual Studio Code

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

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

  • 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.

Fragen / Anmerkungen

Vielen herzlichen Dank!

Fragen
Anmerkungen / Hinweise