Bei großen Kursprojekten in der Informatik gibt es eine Regel: Von den Studierenden, deren Code läuft, scheitert die Hälfte an der Dokumentation. Im README steht nur eine Zeile „run main.py“, der Praktikumsbericht wird ausschließlich mündlich erklärt, die Designbeschreibung enthält kein einziges Bild – bei der Bewertung sieht die Lehrkraft nur die Dokumentation. Die Dokumentations-Pipeline von muchsci ist genau gegen diese Art unsichtbarer Punktabzüge gerichtet.
Dieser Beitrag betrachtet den „Dokumentationsaspekt“ des großen Projekts separat und liefert eine komplette Erstellungs-Pipeline.
Die vier Desaster beim Dokumentationsaspekt
README-Desaster: Eine einzige Ausführungszeile, aber Installation der Abhängigkeiten, Umgebungsanforderungen und Beispieldaten fehlen komplett – die Lehrkraft klont das Projekt und bekommt es nicht zum Laufen; dein Code mag noch so gut sein, er zählt dann null.
Praktikumsbericht-Desaster: Der Code läuft, aber der Bericht ist nicht lesbar – warum diese Lösung gewählt wurde, wie die Parameter festgelegt wurden, wie die Ergebnisse analysiert wurden, alles muss geraten werden.
Designbeschreibungs-Desaster: Kein Architekturdiagramm, die Modulbeziehungen muss man sich komplett vorstellen.
Abgabeformat-Desaster: Markdown einfach so abgegeben, alle Formatpunkte weg – die Lehrkraft will ein ordentlich formatiertes DOCX oder PDF.
Die Erstellungs-Pipeline: Markdown rein, Fertigprodukt raus
Wer Code schreibt, dokumentiert ohnehin gern in Markdown; das Problem liegt nur im „letzten Schritt“. muchsci übernimmt diesen Schritt: Code und Gedanken werden in Markdown festgehalten (für Programmierer kostet das nichts), bei Bedarf wird daraus ein formatiertes Word-Dokument ausgegeben; Architekturdiagramme werden direkt nach Beschreibung erzeugt – „Zeichne ein Drei-Schichten-Architekturdiagramm und markiere die Modulbeziehungen“; Korrektur und einheitliche Formatierung des Praktikumsberichts erledigen sich gleich mit.
Das Erlebnis der ganzen Pipeline: Markdown rein, ordentlich formatiertes Word raus, das Fertigprodukt landet direkt im Abgabeverzeichnis.
Checkliste für den Dokumentationsaspekt und Ansatzpunkte
README in drei Abschnitten: Installation (Umgebung und Abhängigkeiten), Ausführung (Befehl und Parameter), Beispiel (Ein- und Ausgabebeispiel) – muchsci erstellt dir nach dieser Struktur einen Entwurf.
Praktikumsbericht: Umgebung + Methode + Ergebnisanalyse, Daten und Diagramme werden direkt per Skript gezeichnet.
Designbeschreibung: Architekturdiagramm + Modulbeschreibung, Diagramm und Text entstehen zusammen.
Abgabefassung: Normgerechter Word/PDF-Export, einheitliche Formatprüfung.
Wer Code schreiben kann, sollte nicht an der Dokumentation scheitern. Code veraltet, klare Dokumentation bringt immer Pluspunkte – und das nicht nur in diesem Kurs: Wenn du nach dem Kursprojekt das Ganze nebenbei zu Material für dein Portfolio aufbereitest, wirst du dich in der Bewerbungszeit bei deinem jetzigen Ich bedanken.