Seminar Material for MkDocs – Erweiterte Markdown-Komponenten

Material for MkDocs erweitert klassisches Markdown um zahlreiche Komponenten für Hinweise, Code, Registerkarten, Annotationen, Diagramme und wiederverwendbare Inhaltsbausteine. Ohne verbindliche Regeln führt diese Vielfalt jedoch schnell zu inkonsistenten und schwer wartbaren Seiten.

Inhaltsübersicht

• Zielsetzung
• Zielgruppe
• Voraussetzungen
• Seminarinhalte
• Praxisübungen
• Methodik

Zielsetzung

Ein praxistauglicher Komponentenstandard wird entwickelt. Alle zentralen Elemente werden schrittweise aufgebaut, kombiniert, auf typische Fehler geprüft und in wiederverwendbaren Beispielen dokumentiert.

Zielgruppe

Technische Redakteure, Entwickler, Trainer, Supportteams und Autoren technischer Dokumentation.

Voraussetzungen

Sicherer Umgang mit grundlegender Markdown-Syntax; erste Erfahrungen mit MkDocs oder einem vergleichbaren Generator.

Seminarinhalte

Die Themen werden in einer festen Arbeitsfolge aus Analyse, Einrichtung, Umsetzung und Prüfung bearbeitet.

Technisches Markdown und Seitentypen

1. Schritt 1: Überschriften, Listen, Links, Bilder, Tabellen und Code semantisch korrekt einsetzen.
2. Schritt 2: Anleitungen mit Voraussetzungen, nummerierten Schritten und Prüfergebnis strukturieren.
3. Schritt 3: Konzepte, Referenzen, Tutorials und Fehlerbehebungen klar unterscheiden.
4. Schritt 4: Interne Verweise und Medienpfade relativ, stabil und wartbar aufbauen.

Erweiterte Inhaltskomponenten

1. Schritt 1: Hinweise, Details, Tabs, Grids und Annotationen nach fachlichem Zweck auswählen.
2. Schritt 2: Codeblöcke mit Sprache, Markierung, Zeilennummern und erklärenden Anmerkungen gestalten.
3. Schritt 3: Tabellen, Aufgabenlisten, Definitionen und Fußnoten konsistent einsetzen.
4. Schritt 4: Komponentenregeln gegen Überladung und uneinheitliche Verwendung formulieren.

Wiederverwendung und Snippets

1. Schritt 1: Wiederkehrende Inhalte und gemeinsame Warnhinweise identifizieren.
2. Schritt 2: Bausteine in nachvollziehbare Snippet-Dateien auslagern und benennen.
3. Schritt 3: Varianten ohne unübersichtliche Einbindungsketten organisieren.
4. Schritt 4: Änderungen an gemeinsam genutzten Bausteinen mit Referenzseiten absichern.

Diagramme, Formeln und technische Visualisierung

1. Schritt 1: Visualisierungsform nach Informationsziel und Zielgruppe auswählen.
2. Schritt 2: Textbasierte Diagramme und mathematische Formeln kontrolliert integrieren.
3. Schritt 3: Beschriftungen, Legenden und Alternativinformationen bereitstellen.
4. Schritt 4: Responsive Darstellung, Versionsverwaltung und Build-Prüfung absichern.

Barrierefreiheit und zugängliche Struktur

1. Schritt 1: Überschriften, Listen, Tabellen und Landmarken semantisch korrekt strukturieren.
2. Schritt 2: Tastaturwege, Fokusreihenfolge und verständliche Interaktionen prüfen.
3. Schritt 3: Kontraste, Typografie, Zoomverhalten und nichtfarbliche Kennzeichnung bewerten.
4. Schritt 4: Automatisierte Prüfungen mit manueller Abnahme kombinieren.

Qualitätsmodell und Prüfstrategie

1. Schritt 1: Inhaltliche, strukturelle, technische, visuelle und betriebliche Fehler unterscheiden.
2. Schritt 2: Fehler nach Auswirkung, Erkennbarkeit und Korrekturaufwand priorisieren.
3. Schritt 3: Lokale Prüfung, Review-Gate und vollständige Pipeline-Prüfung trennen.
4. Schritt 4: Akzeptanzkriterien und zeitlich begrenzte Ausnahmen dokumentieren.

Praxisübungen

• Eine Referenzseite mit Hinweisen, Tabs, Annotationen und Codebeispielen erstellen
• Wiederkehrende Warnhinweise in Snippets auslagern
• Komponentenregeln für Lesbarkeit, Barrierefreiheit und Pflege festlegen

Methodik

Fachliche Einführung, nachvollziehbare Demonstration, angeleitete Umsetzung, selbstständige Übungsphasen, strukturierte Fehleranalyse und gemeinsame Qualitätskontrolle wechseln einander ab. Alle Arbeitsschritte werden an einem zusammenhängenden Beispielprojekt durchgeführt.