Das ist eine für den Ausdruck optimierte Ansicht des gesamten Kapitels inkl. Unterseiten. Druckvorgang starten.

Zur Standardansicht zurückkehren.

Docs

1 - Diagrams-as-Code

1.1 - Mermaid

Einführung

Mermaid ist eine JavaScript-basierte Diagramm- und Visualisierungsbibliothek, die es ermöglicht, Diagramme und Flussdiagramme mithilfe von Textbeschreibungen zu erstellen. Mermaid wird häufig in Markdown-Dokumenten (z. B. in GitHub, GitLab oder Confluence) verwendet, um komplexe Zusammenhänge visuell darzustellen.

Vorteile von Mermaid:

  • Einfache Integration in Markdown-Dokumente.
  • Keine externen Tools nötig – Diagramme werden direkt im Browser gerendert.
  • Unterstützt eine Vielzahl von Diagrammtypen.
  • Ideal für Dokumentationen, Präsentationen und technische Spezifikationen.

Mögliche Diagramme

Ablauf-Diagramm (Flowchart)

Ablaufdiagramme visualisieren Prozesse oder Workflows. Sie bestehen aus Knoten (Schritte) und Verbindungen (Pfeile), die die Reihenfolge der Schritte darstellen.

Beispiel:

flowchart TD  
A[Start] --> B{Entscheidung}
B -->|Ja| C[Prozess 1]
B -->|Nein| D[Prozess 2]
C --> E[Ende]
D --> E

flowchart TD  
A[Start] --> B{Entscheidung} 
B -->|Ja| C[Prozess 1] 
B -->|Nein| D[Prozess 2] 
C --> E[Ende] 
D --> E

Erklärung:

  • flowchart TD: Definiert ein Ablaufdiagramm von oben nach unten.
  • A[Start]: Ein Knoten mit der Beschriftung “Start”.
  • -->: Verbindung zwischen Knoten.
  • |Ja| und |Nein|: Beschriftungen für die Verbindungen.

Klassen-Diagramm (Class Diagram)

Klassendiagramme zeigen die Struktur von Klassen, ihre Attribute, Methoden und Beziehungen zueinander.

Beispiel:

classDiagram
class Tier {
  -name: String
  +essen()
}
class Hund {
  +bellen()
}
Tier <|-- Hund

classDiagram
class Tier {
  -name: String
  +essen()
}
class Hund {
  +bellen()
}
Tier <|-- Hund

Erklärung:

  • classDiagram: Definiert ein Klassendiagramm.
  • Tier und Hund: Klassen mit Attributen (-name) und Methoden (+essen()).
  • <|--: Vererbungsbeziehung (Hund erbt von Tier).

Sequenz-Diagramm (Sequence Diagram)

Sequenzdiagramme visualisieren Interaktionen zwischen Objekten oder Akteuren in einer zeitlichen Abfolge.

Beispiel:

sequenceDiagram  Alice->>Bob: Hallo! 
Bob-->>Alice: Hallo zurück!

sequenceDiagram  Alice->>Bob: Hallo! Bob-->>Alice: Hallo zurück!

Erklärung:

  • sequenceDiagram: Definiert ein Sequenzdiagramm.
  • Alice->>Bob: Nachricht von Alice an Bob.
  • -->>: Antwort von Bob an Alice.

Entity-Relationship-Diagramm (ER-Diagramm)

ER-Diagramme zeigen die Beziehungen zwischen Entitäten in einer Datenbank.

Beispiel:

erDiagram
  KUNDE ||--o{ BESTELLUNG : "hat"
  KUNDE {
    int *id PK
    string name
  }
  BESTELLUNG {
    int *id PK
    date datum
  }

erDiagram  KUNDE ||--o{ BESTELLUNG : hat KUNDE { int id PK string  name } BESTELLUNG { int id PK date datum }

Erklärung:

  • erDiagram: Definiert ein ER-Diagramm.
  • KUNDE ||--o{ BESTELLUNG: Ein Kunde hat viele Bestellungen.
  • PK: Primärschlüssel.

Status-Diagramm (State Diagram)

Statusdiagramme zeigen die Zustände eines Systems und die Übergänge zwischen diesen Zuständen.

Beispiel:

stateDiagram-v2
    [*] --> Off
    Off --> On: Einschalten
    On --> Off: Ausschalten

stateDiagram-v2
    [*] --> Off
    Off --> On: Einschalten
    On --> Off: Ausschalten

Erklärung:

  • stateDiagram-v2: Definiert ein Statusdiagramm.
  • [*]: Startzustand.
  • Off --> On: Übergang von “Off” zu “On” durch “Einschalten”.

Mindmap-Diagramm

Mindmaps visualisieren hierarchische Ideen oder Konzepte.

Beispiel:

mindmap
  root((Thema))
    Zweig 1
      Unterthema 1
      Unterthema 2
    Zweig 2
      Unterthema 3

mindmap
  root((Thema))
    Zweig 1
      Unterthema 1
      Unterthema 2
    Zweig 2
      Unterthema 3

Erklärung:

  • mindmap: Definiert eine Mindmap.
  • root((Thema)): Zentrales Thema.
  • Einrückungen definieren die Hierarchie.

Anforderungs-Diagramm (Requirement Diagram)

Anforderungsdiagramme zeigen Anforderungen und ihre Beziehungen.

Beispiel:

requirementDiagram
  requirement Anforderung1 {
    id: 1
    text: "Das System muss sicher sein."
  }

  element System {
    type: software
  }

  System - satisfies -> Anforderung1

requirementDiagram
  requirement Anforderung1 {
    id: 1
    text: "Das System muss sicher sein."
  }

  element System {
    type: software
  }

  System - satisfies -> Anforderung1

Erklärung:

  • requirementDiagram: Definiert ein Anforderungsdiagramm.
  • requirement: Definiert eine Anforderung.
  • satisfies: Beziehung zwischen Element und Anforderung.

Gantt-Diagramm

Gantt-Diagramme visualisieren Projektpläne und Zeitachsen.

Beispiel:

gantt
  title Projektplan
  dateFormat YYYY-MM-DD
  section Phase 1
  Aufgabe 1 :a1, 2024-01-01, 7d
  Aufgabe 2 :after a1, 3d

gantt
  title Projektplan
  dateFormat YYYY-MM-DD
  section Phase 1
  Aufgabe 1 :a1, 2024-01-01, 7d
  Aufgabe 2 :after a1, 3d

Erklärung:

  • gantt: Definiert ein Gantt-Diagramm.
  • dateFormat: Format für Datumsangaben.
  • Aufgabe 1 :a1, 2024-01-01, 7d: Aufgabe 1 dauert 7 Tage ab dem 1. Januar 2024.

Zeitlinie (Timeline)

Zeitlinien zeigen Ereignisse in einer chronologischen Abfolge.

Beispiel:

timeline
    title Wichtiges Ereignisse 2024 - 2025
    2024 : Ereignis 1
    2025 : Ereignis 2

timeline
    title Wichtiges Ereignisse 2024 - 2025
    2024 : Ereignis 1
    2025 : Ereignis 2

Erklärung:

  • timeline: Definiert eine Zeitlinie.
  • 2024 : Ereignis 1: Ereignis im Jahr 2024.

Weiterführende Informationen

Mermaid Open-Source

1.2 - PlantUML

Einführung

PlantUML ist ein Open-Source-Tool, das es ermöglicht, Diagramme aus einfachen Textbeschreibungen zu generieren. Es unterstützt eine Vielzahl von Diagrammtypen, sowohl UML-basierte als auch nicht-UML-basierte Diagramme. PlantUML ist besonders nützlich für Entwickler, Architekten und Projektmanager, da es die Erstellung und Pflege von Diagrammen vereinfacht und in viele Entwicklungsumgebungen integriert werden kann.

Mögliche UML-basierte Diagramme

Sequenz-Diagramm

Beschreibung: Ein Sequenzdiagramm zeigt die Interaktion zwischen Objekten in einer bestimmten Reihenfolge. Es wird häufig verwendet, um den Ablauf von Nachrichten zwischen Objekten in einem System zu visualisieren.

Beispiel in PlantUML:

@startuml
Alice -> Bob: Hallo! 
Bob --> Alice: Hallo zurück!
@enduml

Sequenz-Diagramm

Erklärung:

  • -> zeigt eine Nachricht von einem Objekt zum anderen.
  • --> zeigt eine Antwort.

Ablauf-Diagramme

Beschreibung: Ablaufdiagramme (auch Aktivitätsdiagramme genannt) zeigen den Ablauf von Aktivitäten und Entscheidungen in einem Prozess. Sie sind besonders nützlich, um Geschäftsprozesse oder Algorithmen zu visualisieren.

Beispiel in PlantUML:

@startuml 
start
:Aktivität 1; :Aktivität 2; 
if (Bedingung?) then (Ja)
 :Aktivität 3; 
 else (Nein)
 :Aktivität 4; 
 endif 
 stop 
@enduml

Ablauf-Diagramm

Erklärung:

  • start und stop markieren den Beginn und das Ende des Prozesses.
  • if und else zeigen Entscheidungen.

Klassendiagramm

Beschreibung: Klassendiagramme zeigen die Struktur eines Systems durch Klassen, ihre Attribute, Methoden und die Beziehungen zwischen den Klassen.

Beispiel in PlantUML:

@startuml 
class  Auto {   
            -marke: String 
            -modell: String +fahren() 
            }   
class  Fahrer {   
                -name: String +lenken() 
                }   
Auto "1" *-- "1" Fahrer
@enduml

KlassenDiagramm

Erklärung:

  • - zeigt private Attribute, + zeigt öffentliche Methoden.
  • --> zeigt eine Assoziation zwischen Klassen.

Objektdiagramm

Beschreibung: Objektdiagramme zeigen die Instanzen von Klassen zu einem bestimmten Zeitpunkt und deren Beziehungen zueinander.

Beispiel in PlantUML:

@startuml 
object Auto1 {
             marke = "VW" 
             modell = "Golf" 
             }   
object Fahrer1 {
                name = "Max" 
                }   
Auto1 --> Fahrer1 
@enduml

ObjektDiagramm

Erklärung:

  • object definiert eine Instanz einer Klasse.
  • --> zeigt eine Beziehung zwischen Objekten.

Zustandsdiagramm

Beschreibung: Zustandsdiagramme zeigen die verschiedenen Zustände eines Objekts und die Übergänge zwischen diesen Zuständen.

Beispiel in PlantUML:

@startuml 
[*] --> Aus 
Aus --> An : einschalten 
An --> Aus : ausschalten 
@enduml

Zustandsdiagramm

Erklärung:

  • [*] zeigt den Startzustand.
  • --> zeigt einen Übergang zwischen Zuständen.

Mögliche nicht UML-basierte Diagramme

Visualisierung von JSON-/YAML-Daten

Beschreibung: PlantUML kann JSON- oder YAML-Daten visualisieren, um die Struktur und Hierarchie der Daten besser zu verstehen.

Beispiel in PlantUML:

@startjson 
    {
    "name": "Max", 
    "alter": 30, 
    "adresse": { 
                "straße": "Hauptstraße 1", 
                "stadt": "Berlin" 
                } 
    } 
@endjson

JSON/YAML

Erklärung:

  • @startjson und @endjson umschließen den JSON-Code.

Archimate-Diagramm

Beschreibung: Archimate-Diagramme werden verwendet, um Unternehmensarchitekturen zu modellieren. Sie zeigen die Beziehungen zwischen Geschäftsprozessen, Anwendungen und Technologien.

Beispiel in PlantUML:

@startuml 
archimate #Business "Geschäftsprozess" as bp <<business-process>>
archimate #Application "Anwendung" as app <<application-component>>
bp --> app 
@enduml

Archimate

Erklärung:

  • archimate definiert ein Archimate-Element.
  • --> zeigt eine Beziehung zwischen Elementen.

Gantt-Diagramm

Beschreibung: Gantt-Diagramme zeigen Projektpläne und den zeitlichen Ablauf von Aufgaben.

Beispiel in PlantUML:

@startgantt 
[Aufgabe 1] lasts 5 days 
[Aufgabe 2] starts at [Aufgabe 1]'s end and lasts 3 days
@endgantt

Gantt-Diagramm

Erklärung:

  • lasts definiert die Dauer einer Aufgabe.
  • starts at zeigt den Beginn einer Aufgabe relativ zu einer anderen.

Mindmap-Diagramm

Beschreibung: Mindmaps visualisieren Ideen und Konzepte in einer hierarchischen Struktur.

Beispiel in PlantUML:

@startmindmap 
* Root 
** Zweig 1 
*** Blatt 1 
** Zweig 2 
@endmindmap

Mindmap

Erklärung:

  • * zeigt den Root-Knoten.
  • ** und *** zeigen Unterknoten.

Netzwerkdiagramm

Beschreibung: Netzwerkdiagramme zeigen die Struktur und Verbindungen in einem Netzwerk.

Beispiel in PlantUML:

@startuml 
node "Server" as s node 
"Client" as c 
s -- c 
@enduml

Netzwerkdiagramm

Erklärung:

  • node definiert einen Knoten im Netzwerk.
  • -- zeigt eine Verbindung zwischen Knoten.

Projektstrukturplan

Beschreibung: Ein Projektstrukturplan (PSP) zeigt die Hierarchie und Struktur eines Projekts.

Beispiel in PlantUML:

@startwbs 
* Projekt 
** Phase 1 
*** Aufgabe 1 
*** Aufgabe 2 
** Phase 2 
@endwbs

Projektstrukturplan

Erklärung:

  • * zeigt das Hauptprojekt.
  • ** und *** zeigen Unterelemente.

Weiterführende Informationen

2 - Docs-as-Code

2.1 - Asciidoc

Syntax

Da AsciiDoc als “Komplettsystem” angeboten wird, also Sprache inklusive Interpreter, gibt es eine zentrale Syntax. Varianten oder Dialekte wie bei Markdown gibt es bei AsciiDoc nicht.

Kommentare

AsciiDoc-Code kann - wie auch sonstiger Quelltext - kommentiert werden, d.h. Kommentare werden bei der Interpretation des Quelltextes (z.B. bei Umwandlung in ein PDF) nicht berücksichtigt. Damit können Dokumente bzw. Textteile kommentiert werden, oder Hinweise hinterlassen werden.


Das ist ein beliebiger Text in AsciiDoc.

// Diese Zeile wird nicht interpretiert.

Diese Zeile wird angezeigt.

Absätze/Zeilen

AsciiDoc benötigt keine speziellen Angaben für Zeilenschaltungen und Absätze. Der Text wird so umgesetzt wie er geschrieben wurde. Es ist jedoch möglich, eine Zeilenschaltung mit einem Plus-Symbol zu erzwingen. Alternativ kann auch das Attribut [%hardbreaks] vorgesetzt werden.


Dies ist Zeile Nummer Eins.
Dies ist Zeile Nummer Zwei.

Und nun noch ein Absatz.

Diese Zeile wird +
hart umgebrochen.

[%hardbreaks]
Diese Zeilen werden 
wie sie sind dargestellt.

Textformatierung

Fett, Kursiv, Hervorhebung, Code

Um Text fett, kursiv oder als Code darzustellen, gibt es zwei Möglichkeiten, bzw. wird unterschieden, ob es der zu formatierende Text allein steht oder sich in der Mitte eines Textes befindet.

Ein alleinstehendes Wort kann zwischen einzelne Sternchen, Unterstrich, Hashtag oder Gravis-Akzent.


Dieser Text ist *fett*.
Dieser Text ist _kursiv_.
Dieser Text ist `Code`.
Dieser Text ist #hervorgehoben#.

Will man einen Textteil in der Mitte formatieren, wird dies durch doppelte Sternchen, Unterstriche, Hashtag oder Gravis-Akzente erreicht. Würde dies mit einzelnen Zeichen versucht werden, würde die Formatierungsregel ignoriert werden.


Die "tt" in Mi**tt**ag sind fett.
Die "tt" in Mi*tt*ag sind nicht fett.

Die "tt" in Mi__tt__ag sind kursiv.
Die "tt" in Mi_tt_ag sind nicht kursiv.

Die "tt" in Mi``tt``ag sind Code.
Die "tt" in Mi`tt`ag sind nicht Code.

Die "tt" in Mi##tt##ag sind hervorgehoben.
Die "tt" in Mi#tt#ag sind nicht hervorgehoben.

Unterstrichen, Durchgestrichen

Um einen Text durch- bzw. zu unterstreichen, werden Hastags mit einem Attribut verwendet.


Dieser Text ist [.underline]#unterstrichen#.
Dieser Text ist [.line-through]#durchgestrichen#.

Superscript, Subscript und Smart Quotes

Mittels Superscript und Subscript können Textteile hoch- bzw. tiefgestellt werden. Dafür werden die Textteile zwischen einzelne Caret/Zirkumflex (Superscript) oder Tilde (Subscript) gesetzt.


Das ist ein ~Tief~punkt.
Das ist ein ^Höhe^punkt.

Hier ist der vervollständigte AsciiDoc-Text mit Inhalten für die leeren Kapitel (ab „Links“), basierend auf der offiziellen AsciiDoc-Syntax und gängigen Best Practices:

Gerne! Hier ist die überarbeitete Version deiner AsciiDoc-Dokumentation — nun mit kurzer, prägnanter Erklärung zu jedem Kapitel, bevor die Syntaxbeispiele kommen. So bleibt es übersichtlich, verständlich und nützlich für Einsteiger.

Erklärung:
AsciiDoc unterstützt sowohl externe Web-Links als auch interne Verweise innerhalb des Dokuments (Anker) sowie Links auf lokale Dateien. Die Syntax ist einfach und intuitiv — ideal für Dokumentationen, die verlinkt werden sollen.

https://www.asciidoc.org[AsciiDoc Website]

[[abschnitt1]]
== Erster Abschnitt

Siehe auch <<abschnitt1>>.

link:handbuch.pdf[Download Handbuch]

Dokumentenkopf

Erklärung:
Der Dokumentenkopf enthält Metadaten wie Titel, Autor, Datum und globale Attribute. Er ist optional, aber empfehlenswert für strukturierte Dokumente — besonders bei PDF- oder Buch-Exporten.

= Titel des Dokuments
Autor Name <autor@example.com>
:doctype: book
:author: Autor Name
:revdate: 2026-02-09

Automatisches Inhaltsverzeichnis

Erklärung:
Ein Inhaltsverzeichnis (TOC) wird automatisch generiert, sobald das Attribut :toc: gesetzt ist. Es kann links, rechts oder an einer beliebigen Stelle platziert werden — hilfreich für längere Dokumente.

:toc: left

= Haupttitel

== Kapitel 1
Inhalt...

== Kapitel 2
Weiterer Inhalt...

Includes

Erklärung:
Mit include:: kannst du externe AsciiDoc-Dateien oder Teile davon einbinden. Praktisch für wiederverwendbare Abschnitte (z. B. Fußzeilen, Hinweise, Kapitel).

include::kapitel1.adoc[]

include::../shared/footnotes.adoc[tag=abschnitt2]

Listen

Erklärung:
AsciiDoc unterstützt Aufzählungslisten (*), nummerierte Listen (.) und Definitionen (::). Die Einrückung bestimmt die Hierarchie — einfach und klar strukturiert.

Aufzählungslisten

* Punkt 1
* Punkt 2
  * Unterpunkt

Nummerierte Listen

. Erster Punkt
. Zweiter Punkt
.. Unterpunkt

Definitionen

Begriff::
  Definition des Begriffs.

Bilder

Erklärung:
Bilder werden mit image:: eingebunden. Du kannst Größe, Alternativtext und Skalierung steuern. Funktioniert in HTML, PDF und EPUB — je nach Backend.

image::logo.png[Logo, 200, 100]

image::diagramm.svg[Diagramm, scaledwidth=50%]

Audio

Erklärung:
Audio-Dateien (z. B. Sprachnachrichten) können direkt im Dokument eingebunden werden. Nützlich für Tutorials oder multimediale Dokumentationen.

audio::sprachnachricht.mp3[Sprachnachricht, autoplay]

Videos

Erklärung:
Videos werden mit video:: eingebunden. Du kannst Steuerungselemente wie autoplay, controls oder loop aktivieren — ideal für Anleitungen oder Präsentationen.

video::tutorial.mp4[Tutorial, width=640, height=360, autoplay, controls]

Tastatur, Button Menü Macros

Erklärung:
Mit kbd: und menu: kannst du Tastaturbefehle und Menüpfade klar hervorheben — besonders nützlich in Anleitungen oder Software-Dokumentationen.

Tastaturbefehle

Drücke kbd:[Strg+C] zum Kopieren.

Menübefehle

Gehe zu menu:Datei[Speichern unter...].

Sourcecode

Erklärung:
Codeblöcke mit Syntax-Highlighting werden mit [source] eingeleitet. Du kannst Sprachen wie Python, Bash oder HTML angeben — hilfreich für Entwicklerdokumentationen.

[source,python]
----
def hello():
    print("Hallo Welt")
----

Hinweise, Textblöcke

Erklärung:
Mit NOTE:, TIP:, WARNING: usw. kannst du wichtige Informationen hervorheben. Zitate mit ____ sind ideal für Zitate oder Zitate aus externen Quellen.

Hinweise

NOTE: Dies ist eine wichtige Information.

TIP: So geht’s schneller.

Zitate

____
„Das ist ein Zitat.“
— Autor
____

Tabellen

Erklärung:
Tabellen werden mit |=== definiert. Jede Zelle wird mit | getrennt. Du kannst Spaltenanzahl, Rahmen und Beschriftungen steuern — perfekt für Vergleiche oder Daten.

|===
| Spalte 1 | Spalte 2
| Wert A   | Wert B
| Wert C   | Wert D
|===

IDs, Rollen und Optionen

Erklärung:
Mit [[id]] setzt du Anker für interne Links. Mit [.rolle] kannst du CSS-Klassen zuweisen. Mit [%option] steuerst du Blockverhalten (z. B. unnummeriert).

IDs

[[kapitel2]]
== Kapitel 2

Rollen

[.hinweis]
Dieser Text hat eine Rolle.

Optionen

[%unnumbered]
== Dieser Abschnitt hat keine Nummer.

Attribute und Sonderzeichen

Erklärung:
Attribute (:name: wert) ermöglichen Wiederverwendung von Text oder Werten. Sonderzeichen wie + oder \\ müssen ggf. escaped werden, um nicht als Formatierung interpretiert zu werden.

Attribute

:version: 1.0

Die Version ist {version}.

Sonderzeichen

+ für Plus, \\ für Backslash, &#x27; für Apostroph.

Quellenverzeichnis

Erklärung:
Ein Literaturverzeichnis kann manuell oder über bibliography:: erstellt werden. Nützlich für wissenschaftliche oder referenzierte Dokumente.

[bibliography]
== Literatur

- Autor, Titel, Verlag, Jahr

Fussnoten

Erklärung:
Fußnoten werden mit footnote:[Text] oder [footnote:] eingefügt. Sie erscheinen am Ende des Dokuments oder der Seite — ideal für ergänzende Informationen.

Dies ist ein Satz mit einer Fußnote.footnote:[Das ist die Fußnote.]

Ein weiterer Satz mit [footnote:2]Fußnote 2[footnote:2].

Fazit

Vorteile

Ein grosser Vorteil von AsciiDoc ist sicher der grosse Funktionsumfang, mit dem sogar komplexe Dokumente mit Inhaltsverzeichnis und Quellenverzeichnis möglich sind. Auch die Include-Funktion und mögliche Kommentare erleichtern den Umgang mit viel Text und vielen Dateien, auch eine kollaborative Bearbeitung ist dadurch einfach. Da AsciiDoc nicht einfach nur eine Sprache, sondern auch ein Anwendung mitgeliefert wird, kann ohne grosse Umschweife produktiv damit gearbeitet werden. Ausser einem Texteditor für die Textdateien, wird sonst nichts weiteres benötigt.

Nachteile

AsciiDoc ist bei weitem nicht so stark verbreitet wie Markdown. Produktive Tools wie Notiz-Apps, Wikis oder Static Site Generatoren unterstützen nur selten AsciiDoc und wenn, dann meist nur mittels Plugins. Wer viel mit solchen Tools arbeitet, wird um die parallele Verwendung von Markdown und AsciiDoc nicht herumkommen.

Weiterführende Informationen

Literatur

Tools zur Anwendung von AsciiDoc

Texteditoren

Static Site Generatoren

Transformations-Werkzeuge

2.2 - Markdown

Markdown ist sicher die verbreiteteste einfache Ausschreibungssprache.

Syntax

Basic-Syntax

Hierbei handelt es sich um die Grundbefehle, die Markdown bietet und grundsätzlich in jedem Tool funktionieren sollten.

Überschriften

Um Überschriften darzustellen, wird dem Überschriftentitel ein oder mehrere Hashtags vorgesetzt. Je nach Ebene.

# Überschrift 1

## Überschrift 2

### Überschrift 3

#### Überschrift 4

##### Überschrift 5

###### Überschrift 6

Hinweis: Am besten immer eine Leerzeile vor einer Überschrift einfügen, da ohne die Interpretationen nicht korrekt sein kann.

Absätze/Zeilen

Für Zeilenschaltungen und Absätze gibt es keine wirklichen Notationen, sondern hier wird der Text wie geschrieben angezeigt. Als Unterstützung kann für eine Zeilenschaltung ein doppeltes Leerzeichen an das Ende der Zeile eingefügt werden, oder alternativ auch der HTML-Tag <br>.


Erste Zeile mit zwei Leerzeichen am Schluss.  
Und nun die nächste Zeile.

Erste Zeile mit dem HTML-Tag am Schluss.<br>
Und nun die nächste Zeile.

Textformatierung

Standardmässig bietet Markdown die Möglichkeit, Text als Fett und/oder Kurisv darzustellen.

Um einen Text fett darzustellen, wird der entsprechende Textteil zwischen doppelten Sternen oder Underscores geschrieben.


Bei mir gibt es auch **fetten Text**.

Bei mir gibt es auch __fetten Text__.

Und hier gibt es **fetten Text** in der Mitte.

Um einen Text kursiv darzustellen, wird der entsprechende Textteil zwischen einfachen Sternen oder Underscores geschrieben.


Bei mir gibt es auch *kursiven Text*.

Bei mir gibt es auch _kursiven Text_.

Und hier gibt es *kursiven Text* in der Mitte.

Natürlich lässt sich es sich auch kombinieren:

Um einen Text fett darzustellen, wird der entsprechende Textteil zwischen doppelten Sternen oder Underscores geschrieben.


Bei mir gibt es  ***fetten und kursiven Text***.

Bei mir gibt es auch ___fetten und kursiven Text___.

Und hier gibt es ***fetten und kursiven Text*** in der Mitte.

Blockzitate

Um einen Text als Block zu zitieren, wird einfach ein “Grösser als”-Zeichen vor die Zeile gesetzt.


> Dieser Text befindet sich in einem Blockzitat.

Wenn das Blockzitat mehrere Zeilen umfassen soll, muss am Anfang jeder Zeile (auch bei leeren Zeilen) das “Grösser als”-Zeichen gesetzt werden.


> Dieser Text stellt die erste Zeile im Blockzitat dar.
> 
> Und hier gibt es die nächste Zeile.

Zitate können auch ineinander verschachtelt werden, hier wird in der nächsten Ebene bzw. zur Einrückung ein weiteres “Grösser als”-Zeichen gesetzt.


> Dieser Text befindet sich in einem Blockzitat.
> 
>> Dieser Text ist in der Verschachtelung.

Listen

Listen sind genauso einfach und werden einfach im Text geschrieben. Geht es in der Liste in eine weitere Ebene, wird dies durch eine Einrückung (4 Leerzeichen bzw. 1 Tab) ermöglicht.

Sortierte Liste

Sortierte Listen werden generiert, in dem einfach die entsprechende Zahl inklusive einem Punkt vor die Zeile gesetzt wird.


1. Erster Punkt
2. Zweiter Punkt
3. Dritter Punkt
    1. erste Einrückung
    2. zweite Einrückung
4. Vierter Punkt
Unsortierte Liste

Unsortierte Listen werden generiert, in dem einfach ein Bindestich vor die Zeile gesetzt wird.


- Erster Punkt
- Zweiter Punkt
- Dritter Punkt
    - erste Einrückung
    - zweite Einrückung
- Vierter Punkt

Um einen Link darzustellen, wird der Linktext in eckige Klammer gesetzt, gefolgt von der URL innerhalb von Rundklammern.

Sortierte Listen werden generiert, in dem einfach die entsprechende Zahl inklusive einem Punkt vor die Zeile gesetzt wird.


Meine liebste Suchmaschine ist [Swisscows](https://swisscows.com/de).

```markdown

Dem Link kann auch ein zusätzlicher Titel als Tooltip hinzugefügt werden.

```markdown

Meine liebste Suchmaschine ist [Swisscows](https://swisscows.com/de "Die schweizer Suchmaschine").

Als Kurzform kann eine URL auch einfach innerhalb von Spitzklammern geschrieben werden.


Meine liebste Suchmaschine ist <https://swisscows.com/de>.

Erweiterte Syntax

Gerne! Hier ist der ergänzte Abschnitt „Erweiterte Syntax“ mit präzisen, kurzen Erklärungen zu den fehlenden Punkten – im gleichen Stil wie deine Doku:

Erweiterte Syntax

Tabellen

Tabellen werden mit senkrechten Strichen (|) und Bindestrichen (-) definiert. Die erste Zeile enthält die Spaltenüberschriften, die zweite Zeile definiert die Ausrichtung (optional).

| Links ausgerichtet | Zentriert       | Rechts ausgerichtet |
| :--------------- | :-------------: | ------------------: |
| Zelle 1          | Zelle 2         | Zelle 3             |
| Zelle 4          | Zelle 5         | Zelle 6             |

Hinweis: Die Anzahl der Bindestriche in der Trennzeile ist beliebig, wichtig ist nur das : für die Ausrichtung.

Code Blocks

Für mehrzeiligen Code wird ein Code Block mit drei Backticks (```) oder mit vier Leerzeichen pro Zeile erstellt. Optional kann die Sprache angegeben werden, um Syntax-Highlighting zu aktivieren.

```python
def hello():
    print("Hello, World!")


---

#### Fussnoten

Fussnoten werden mit `[^Kennung]` im Text eingefügt und am Ende der Datei mit `[^Kennung]:` definiert.

```markdown
Hier steht ein Text mit einer Fussnote.[^1]

[^1]: Das ist die Erklärung zur Fussnote.

Hinweis: Nicht alle Markdown-Parser unterstützen Fussnoten – z. B. Hugo benötigt goldmark mit aktivierter Option.

IDs für Überschriften

Überschriften können mit einer ID versehen werden, um sie direkt zu verlinken (z. B. für Inhaltsverzeichnisse oder Ankerlinks).

## Überschrift mit ID {#meine-id}

[Link zur Überschrift](#meine-id)

Hinweis: In Hugo muss enableInlineShortcodes = true in der Konfiguration aktiviert sein.

Aufgabenlisten

Aufgabenlisten (Checklisten) werden mit - [ ] für ungeprüfte und - [x] für geprüfte Items erstellt.

- [x] Aufgabe erledigt
- [ ] Noch zu erledigen
- [ ] Wird später gemacht

Hinweis: Wird oft in GitHub, GitLab oder Notiz-Apps wie Obsidian genutzt.

Durchgestrichen

Durchgestrichener Text wird mit doppelten Tilden (~~) umschlossen.

Dieser Text ist ~~durchgestrichen~~.

Emojis

Emojis können direkt eingefügt werden (z. B. 😊) oder mit Shortcodes wie :smile: (je nach Parser).

Ich bin heute gut gelaunt 😊

Hinweis: In Hugo müssen Emojis explizit aktiviert werden (enableEmoji = true).

Hervorheben von Text

Einige Parser (z. B. Hugo mit Goldmark) unterstützen Hervorhebungen mit ==:

Dieser Text ist ==hervorgehoben==.

Hinweis: Nicht standardisiert – funktioniert nicht überall.

Sub-/Superscript

Subscript (H₂O) und Superscript (x²) werden mit ~ bzw. ^ dargestellt – aber nur in einigen Erweiterungen wie Pandoc oder Hugo mit speziellem Parser.

Wasser ist H~2~O.  
x^2^ ist x hoch 2.

Hinweis: Nicht Teil des CommonMark-Standards – Funktioniert z. B. in Hugo mit goldmark und aktivierter Option.

Falls du möchtest, kann ich dir auch ein vollständiges, aktualisiertes Markdown-Referenzdokument im Hugo-Format als Download bereitstellen – sag einfach Bescheid!

Verwendung

Markdown stellt kein eigenes System dar, sondern steht rein für eine offene und frei verfügbare Syntax. Man könnte Markdown auch mit einer integrierbaren Scriptsprache vergleichen. Dies ist sicher auch der Grund, wieso so viele Systeme Markdown unterstützen und die Sprache dadurch so vielseitig verwendbar ist.

Wiki-Systeme

Wiki-Systeme wie z.B. Mediawiki (auf dem Wikipedia aufbaut), dokuWiki oder integrierte Wiki-Funktionen wie z.B. bei Github oder Gitlab setzen standardmässig auf Markdown zur Verwaltung der Inhalte.

Wikis sind ja vor allem dazu da, Inhalte zu präsentieren, im Git-Bereich Dokumentationen zur angebotenen Software. Dank der einfachen Syntax können diese auch von Nicht-Techies erstellt und verwaltet werden.

Notizen

Auch die vielfach verfügbaren Notiz-Apps (oder teilweise auch Desktop-Wikis genannt) greifen für die Verwaltung der Inhalte auf Markdown zurück. Oft wird ein integrierter WYSIWYG-Editor zur Verfügung gestellt, jedoch verwendet dieser im Hintergrund Markdown. Es gibt auch meist die Möglichkeit, auf den Quelltext umzustellen und dort direkt zu bearbeiten. Beispiele hierfür sind Zim, Zettlr, QOwnNotes und Logseq im Open-Source-Bereich oder populäre Varianten wie Evernote, Obsidian oder Joplin.

Webseiten

Im Bereich Webseiten kommt Markdown in zweierlei Hinsicht vor. Zum einen bieten die bekannten Content Management Systeme (wie z.B. Wordpress und Drupal) oft Plugins/Module, um Inhalte in Markdown zu veröffentlichen. Aber neben CMS gibt es auch SSG, sogenannte Static Site Generatoren, wie z.B. Hugo oder Jekyll. Dazu gibt es noch ähnliche auf technische Dokumentationen spezialisierte Systeme wie MKDocs, Sphinx oder Docusaurus. Auch hier werden die ganzen Inhalte in Markdown angelegt und dann mittels Preprocessor in statische Webseiten umgewandelt, die dann veröffentlicht werden können.

Präsentationen/Kurse

Neben Webseiten, können mit Markdown auch Präsentationen erstellt werden. Jedoch handelt es sich hier nicht um Powerpoint-Präsentationen, sondern werden diese mittels Preprocessoren dynamisch in Webelemente umgewandelt. Beispiele sind hierfür Marp, remarkJS oder Cleaver. Speziell für Online-Kurse bietet sich die Markdown-Erweiterung LiaScript an.

Dokumente

Markdown fehlen sicher einige Funktionalitäten, wie sie eine Textverarbeitung wie MS Word oder LibreOffice Writer vorweisen können, doch reicht es für einfache Dokumente wie z.B. Briefe vollkommen aus.

Fazit

Vorteile

Markdown hat eine einfache und klare Syntax, ist demzufolge leicht zu erlernen. Markdown-Dokumente haben auch den Vorteil, dass sie selbst im Quelltext leicht lesbar sind. Sie sind also sowohl maschinen- als auch menschenlesbar. Letzteres dank der einfachen und geradlinigen Syntax ohne Overhead. Auch die grosse Verbreitung von Markdown, der Integration in so viele Tools spricht für sich.

Nachteile

Neben den klaren Vorteilen, gibt es aber leider auch negatives über Markdown zu berichten.

Markdown eignet sich sehr gut für Artikel und Notizen, die nicht so komplex aufgebaut sind. Möchte man mehr und z.B. grosse und komplexe Dokumente erstellen, wie z.B. ganze Bücher, fehlen nützliche Funktionen wie Inhaltsverzeichnis oder die Möglichkeit, Dateien mittels “Include” zu verschachteln.

Zwar gibt es mit CommonMark einen Markdown-Standard, doch die starke Verbreitung hat doch zu vielen “Dialekten” geführt, da viele Tools die Standard-Syntax durch eigene Befehle erweitern. Dadurch sind Markdown-Dokumente aus verschiedenen Systemen nicht zwingend untereinander kompatibel.

Weiterführende Informationen

Literatur

Tools zur Anwendung von Markdown

Desktop-Wikis

Texteditoren

Static Site Generatoren

Transformations-Werkzeuge

3 - Documentation Engineering

Documentation Engineering – Definition, Zweck und Einordnung

Was ist Documentation Engineering?

Documentation Engineering bezeichnet einen systematischen, ingenieurhaften Ansatz zur Planung, Erstellung, Strukturierung, Pflege und Weiterentwicklung von Dokumentation.

Im Zentrum steht nicht das einzelne Dokument, sondern Dokumentation als gestaltbares System:
mit klaren Strukturen, definierten Abhängigkeiten, Rollen, Werkzeugen und Lebenszyklen.

Documentation Engineering betrachtet Dokumentation damit ähnlich wie Software, Architekturen oder Geschäftsprozesse:
als etwas, das entworfen, betrieben und kontinuierlich verbessert werden muss.

Wozu ist Documentation Engineering gut?

Documentation Engineering adressiert typische Probleme klassischer Dokumentation:

  • Dokumentation ist unvollständig oder veraltet
  • Wissen ist personengebunden oder über viele Silos verteilt
  • Dokumente sind schwer auffindbar oder widersprüchlich
  • Änderungen sind aufwendig und fehleranfällig
  • Dokumentation wächst unkontrolliert mit Organisation und Systemlandschaft

Der Ansatz hilft dabei,

  • Überblick über komplexe Sachverhalte zu behalten
  • Konsistenz über viele Inhalte hinweg sicherzustellen
  • Nachhaltigkeit bei personellen oder organisatorischen Veränderungen zu erreichen
  • Dokumentation skalierbar an Unternehmensgrösse und -komplexität anzupassen
  • Dokumentation als Arbeitsinstrument statt als reine Ablage zu nutzen

Was unterscheidet Documentation Engineering von klassischer Dokumentation?

Klassische Dokumentation fokussiert oft auf:

  • einzelne Dokumente
  • Textinhalte
  • manuelle Pflege
  • statische Formate

Documentation Engineering hingegen fokussiert auf:

  • Strukturen statt Einzeltexte
  • Zusammenhänge statt isolierte Inhalte
  • Wiederverwendbarkeit statt Redundanz
  • Prozesse und Werkzeuge statt einmaliger Erstellung

Kurz gesagt:

Klassische Dokumentation beantwortet Was wird dokumentiert?
Documentation Engineering beantwortet Wie wird Dokumentation als System gestaltet?

Zentrale Prinzipien von Documentation Engineering

Auch ohne festes Framework lassen sich typische Grundprinzipien erkennen:

1. Struktur vor Inhalt

Bevor Inhalte entstehen, wird geklärt:

  • welche Arten von Informationen existieren
  • wie sie zueinander in Beziehung stehen
  • wie tief sie dokumentiert werden sollen

2. Trennung von Inhalt und Darstellung

Inhalte werden unabhängig vom Ausgabemedium gepflegt.
Die Darstellung (Web, PDF, Wiki, Präsentation) ist nachgelagert.

3. Modularität und Wiederverwendung

Informationen werden so aufbereitet, dass sie:

  • mehrfach verwendet
  • kontextabhängig kombiniert
  • zentral gepflegt werden können

4. Lebenszyklusdenken

Dokumentation hat:

  • einen Entstehungskontext
  • eine Nutzungsphase
  • Änderungsanlässe
  • ein mögliches Ende

Documentation Engineering berücksichtigt diesen Lebenszyklus explizit.

Wie kann Documentation Engineering umgesetzt werden?

Documentation Engineering ist kein einzelnes Tool, sondern eine Kombination aus:

  • Denkmodell
  • Strukturprinzipien
  • Rollen
  • Prozessen
  • Werkzeugen

Je nach Kontext kommen unterschiedliche Umsetzungsansätze zum Einsatz.

Docs-as-Ecosystems

Der Begriff Docs-as-Ecosystems beschreibt Dokumentation als vernetztes System aus:

  • Inhalten
  • Metadaten
  • Beziehungen
  • Versionen
  • Zielgruppen

Dokumentation wird dabei nicht als Sammlung einzelner Dateien verstanden, sondern als Informationslandschaft, die mit dem Unternehmen mitwächst.

Typische Merkmale:

  • klare Navigations- und Verlinkungslogik
  • mehrere Einstiegspunkte für unterschiedliche Zielgruppen
  • lose Kopplung statt monolithischer Dokumente

Docs-as-Code

Docs-as-Code überträgt bewährte Prinzipien aus der Softwareentwicklung auf Dokumentation:

  • Versionskontrolle (z. B. Git)
  • Reviews und Freigaben
  • Automatisierte Builds
  • Nachvollziehbare Änderungen

Vorteile:

  • Transparenz bei Änderungen
  • bessere Zusammenarbeit
  • geringere Abhängigkeit von einzelnen Personen
  • bessere Integration in bestehende Entwicklungsprozesse

Docs-as-Code ist kein Selbstzweck, sondern ein Enabler für nachhaltige Dokumentation.

Diagrams-as-Code

Diagrams-as-Code erweitert den Ansatz auf grafische Inhalte:

  • Diagramme werden textuell beschrieben
  • sie sind versionierbar
  • sie lassen sich automatisiert erzeugen

Beispiele:

  • Architekturdiagramme
  • Prozessdarstellungen
  • Abhängigkeitsübersichten

Der Vorteil liegt nicht primär in der Technik, sondern in:

  • Konsistenz zwischen Text und Grafik
  • besserer Wartbarkeit
  • geringerem Medienbruch

Rollen und Verantwortlichkeiten

Documentation Engineering erfordert klare Zuständigkeiten, zum Beispiel:

  • inhaltliche Verantwortung (Was ist korrekt?)
  • strukturelle Verantwortung (Wo gehört etwas hin?)
  • technische Verantwortung (Wie wird es erzeugt?)

Diese Rollen müssen nicht zwingend Vollzeitstellen sein, sollten aber klar benannt sein.

Wann lohnt sich Documentation Engineering?

Der Ansatz ist besonders sinnvoll, wenn:

  • Organisationen wachsen oder sich verändern
  • Systeme und Prozesse komplexer werden
  • Wissen nicht mehr informell weitergegeben werden kann
  • Dokumentation strategische Bedeutung erhält
  • regulatorische oder organisatorische Anforderungen steigen

Für sehr kleine, stabile Umgebungen kann klassische Dokumentation ausreichen.
Mit zunehmender Komplexität steigt jedoch der Nutzen eines systematischen Ansatzes deutlich.

Fazit

Documentation Engineering ist kein neues Schlagwort, sondern die konsequente Anwendung ingenieurhaften Denkens auf Dokumentation.

Es hilft dabei,

  • Dokumentation planbar zu gestalten
  • Komplexität beherrschbar zu machen
  • Wissen nachhaltig verfügbar zu halten

Nicht durch mehr Dokumente, sondern durch bessere Struktur, klare Verantwortung und geeignete Werkzeuge.

Gute Dokumentation entsteht nicht zufällig –
sie ist das Ergebnis bewusster Gestaltung.

Weiterführende Informationen

Literatur

4 - Enterprise Architecture Management

Enterprise Architecture Management (EAM) ist ein strategisches Managementinstrument, das Organisationen dabei unterstützt, ihre IT-Infrastruktur und Geschäftsprozesse aufeinander abzustimmen. Es schafft Transparenz über die Architektur der Organisation und ermöglicht eine zielgerichtete Weiterentwicklung von Geschäftsmodellen, Applikationen und Technologien.

Ebenen

Geschäftsebene

Die Geschäftsebene beschreibt die strategischen Ziele, Geschäftsprozesse, Organisationseinheiten und Rollen der Unternehmung. Sie bildet die Grundlage für alle weiteren Ebenen.

  • Ziele: Strategische Ausrichtung, Wertschöpfung, Kundennutzen
  • Prozesse: End-to-End-Geschäftsprozesse (z. B. Auftragsabwicklung, Kundenservice)
  • Organisation: Struktur, Rollen, Verantwortlichkeiten
  • Informationen: Geschäftsdaten, Kennzahlen, Regelwerke

Beispiel: Ein Bankgeschäft beschreibt die Prozesse „Kreditantrag stellen“, „Bonitätsprüfung“, „Vertragsabschluss“.

Applikationsebene

Die Applikationsebene beschreibt die Software-Systeme und Anwendungen, die zur Unterstützung der Geschäftsprozesse eingesetzt werden.

  • Anwendungen: ERP-Systeme, CRM-Tools, Portale, Microservices
  • Integrationen: Schnittstellen zwischen Systemen (APIs, Middleware)
  • Datenflüsse: Wie Daten zwischen Anwendungen ausgetauscht werden
  • Funktionale Abhängigkeiten: Welche Anwendung welche Geschäftsprozesse unterstützt

Beispiel: SAP ERP unterstützt die Buchhaltung, Salesforce CRM den Vertrieb.

Technikebene

Die Technikebene beschreibt die IT-Infrastruktur, auf der die Applikationen laufen.

  • Hardware: Server, Rechenzentren, Endgeräte
  • Software: Betriebssysteme, Datenbanken, Middleware
  • Netzwerke: LAN, WAN, Cloud-Infrastruktur
  • Sicherheit & Compliance: Zugriffssteuerung, Verschlüsselung, Backup

Beispiel: Virtualisierte Umgebung mit Kubernetes, PostgreSQL-Datenbank, Azure-Cloud-Hosting.

Frameworks

TOGAF (The Open Group Architecture Framework)

TOGAF ist das weltweit am häufigsten verwendete EAM-Framework. Es bietet einen strukturierten Ansatz zur Entwicklung und Verwaltung von Unternehmensarchitekturen.

  • ADM (Architecture Development Method): 8-Phasen-Prozess zur Architekturentwicklung
  • Content Framework: Vorlagen für Architekturartefakte (z. B. Sichten, Modelle)
  • Enterprise Continuum: Klassifizierung von Architekturen (von generisch bis spezifisch)
  • TOGAF Standard: Offen, erweiterbar, von der Open Group gepflegt

Vorteile: Breite Akzeptanz, gut dokumentiert, skalierbar
Nachteile: Komplex, hoher Einarbeitungsaufwand

Zachman Framework

Das Zachman Framework ist ein Klassifikationsschema, das Architekturinformationen nach zwei Dimensionen strukturiert: Perspektiven (Wer? – vom CEO bis zum Techniker) und Aspekte (Was? Wo? Wie? Wann? Warum?).

  • 6 Perspektiven: Planer, Owner, Designer, Builder, Subcontractor, Enterprise
  • 6 Aspekte: Data, Function, Network, People, Time, Motivation
  • 6x6-Matrix: Jede Zelle enthält einen spezifischen Architekturartefakt

Vorteile: Sehr strukturiert, gut für Dokumentation und Abdeckung
Nachteile: Kein Prozess, keine Implementierungshilfe

DYNAMAP (Dynamic Architecture Management)

DYNAMAP ist ein modernes, agiles EAM-Framework, das insbesondere für digitale Transformation und dynamische Organisationen entwickelt wurde.

  • Fokus auf Agilität: Schnelle Anpassung an Markt- und Technologieveränderungen
  • Modellgetriebene Architektur: Nutzung von Modellen zur Automatisierung und Simulation
  • Integrationsfähigkeit: Verknüpft EAM mit DevOps, Cloud und AI
  • Wertorientierung: Betont den Geschäftswert jeder Architekturkomponente

Vorteile: Flexibel, digital ausgerichtet, gut für Cloud- und Plattformstrategien
Nachteile: Weniger etabliert, weniger Standardisierung

Weiterführende Informationen

Literatur

Hier einige Bücher, die ich zu Enterprise Architecture gelesen habe und sehr empfehlen kann:

Einige Links zu und um EAM Frameworks:

Tools zur Umsetzung von EAM

Es gibt auf dem Markt sehr viele Software-Produkte, mit denen Architekturen aufgebaut und verwaltet werden können. Ich konzentriere mich hier vor allem auf frei verfügbare Varianten, die man einfach runterladen und nutzen kann: