Seminar MkDocs – API-Dokumentation und Code-Referenzen

API-Dokumentation verbindet Quellcode, automatisch erzeugte Referenzen, handgeschriebene Konzepte und ausführbare Beispiele. Das Seminar zeigt, wie diese Bestandteile in einem MkDocs-Projekt sauber getrennt, verknüpft und in der Build-Pipeline geprüft werden.

Inhaltsübersicht

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

Zielsetzung

Ein durchgängiger Prototyp für eine Code-Referenz entsteht: von Docstrings und Informationsarchitektur über generierte API-Seiten bis zu Querverweisen, Beispielen und Qualitätsprüfungen.

Zielgruppe

Softwareentwickler, Developer-Experience-Teams, technische Redakteure mit Codebezug und Verantwortliche für SDK- oder Bibliotheksdokumentation.

Voraussetzungen

Sichere Python-Grundkenntnisse, Git-Praxis und Grundkenntnisse in MkDocs sowie Markdown.

Seminarinhalte

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

Architektur für API- und Code-Referenzen

1. Schritt 1: Tutorials, Anleitungen, Konzepte und automatisch erzeugte Referenz klar trennen.
2. Schritt 2: Quellcode, handgeschriebene Texte und generierte Seiten im Repository ordnen.
3. Schritt 3: Öffentliche Schnittstellen als verständliches Navigationsmodell abbilden.
4. Schritt 4: Verantwortlichkeiten zwischen Entwicklung und Redaktion festlegen.

Docstrings und ausführbare Beispiele

1. Schritt 1: Parameter, Rückgabewerte, Ausnahmen und Beispiele konsistent dokumentieren.
2. Schritt 2: Typinformationen und Docstrings auf Widersprüche prüfen.
3. Schritt 3: Beispiele klein, vollständig, versionsbezogen und testbar formulieren.
4. Schritt 4: Sensible Laufzeitwerte und ungeeignete Produktionsdaten entfernen.

Automatische Referenzerzeugung

1. Schritt 1: Geeignetes API-Dokumentations-Plugin installieren und konfigurieren.
2. Schritt 2: Importpfade, Handler, Auswahlregeln und Darstellungsoptionen festlegen.
3. Schritt 3: Referenzseiten manuell, halbautomatisch oder vollständig generiert anlegen.
4. Schritt 4: Ausgabe auf Vollständigkeit, Reihenfolge und Lesbarkeit prüfen.

Querverweise und Versionsbezug

1. Schritt 1: Stabile interne Verweise zwischen Konzepten, Beispielen und API-Objekten herstellen.
2. Schritt 2: Mehrdeutige Symbolnamen und tote Referenzen erkennen.
3. Schritt 3: API-Dokumentation eindeutig einer Softwareversion zuordnen.
4. Schritt 4: Änderungen, veraltete Funktionen und Migrationshinweise kennzeichnen.

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.

CI/CD-Stufenmodell

1. Schritt 1: Ereignisse für Prüfung, Vorschau, Freigabe und Veröffentlichung festlegen.
2. Schritt 2: Pipeline-Stufen nach Geschwindigkeit, Risiko und Abhängigkeit ordnen.
3. Schritt 3: Artefakte, Protokolle und Freigaben als überprüfbare Ergebnisse definieren.
4. Schritt 4: Abbruch-, Wiederanlauf- und Fehlerregeln vor der Implementierung festlegen.

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.

HTML-, Barriere- und Regressionstests

1. Schritt 1: Erzeugte Seiten auf erwartete Titel, Metadaten und Navigation prüfen.
2. Schritt 2: Semantische HTML-Struktur, eindeutige IDs und Alternativtexte kontrollieren.
3. Schritt 3: Kritische Seitentypen und Bildschirmgrößen für visuelle Vergleiche auswählen.
4. Schritt 4: Beabsichtigte und fehlerhafte Darstellungsänderungen nachvollziehbar unterscheiden.

Praxisübungen

• Docstrings nach einem konsistenten Schema überarbeiten
• Referenzseiten aus einem Beispielpaket erzeugen und in die Navigation integrieren
• Konzeptseite, API-Referenz und ausführbares Beispiel miteinander verknüpfen

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.