Zum Inhalt

An der Dokumentation mitwirken

Diese Dokumentation ist ein offenes Repository – jedes Orchestermitglied darf und soll Inhalte ergänzen, korrigieren oder neu strukturieren. Dieser Abschnitt erklärt, wie man dabei vorgeht.

1. GitLab-Zugang

Das Repository liegt unter https://gitlab.com/aachener-studentenorchester/documentation in der GitLab-Gruppe des ASO.

  1. Account. Wer noch keinen GitLab-Account hat, registriert sich kostenlos unter https://gitlab.com.
  2. Zugriff. Damit man Änderungen vorschlagen kann, muss der eigene Account als Mitglied der GitLab-Gruppe hinzugefügt werden. Dafür bitte beim Kassenwart melden (aktuell auch Administrator der GitLab-Gruppe).

2. Der empfohlene Weg: Claude Code

Der aktuell einfachste und empfohlene Weg, Inhalte zu dieser Dokumentation beizutragen, ist Claude Code – das KI-Tool von Anthropic, mit dem auch große Teile dieser Dokumentation erstellt wurden.

Warum das einfach ist:

  1. Kein Markdown-Know-how nötig. Man muss die Markdown-Syntax nicht selbst beherrschen. Claude kennt sie und setzt Überschriften, Listen und Links korrekt um.
  2. Kein Git-Kommandozeilen-Wissen nötig. Claude führt Git-Operationen (Branch anlegen, committen, pushen, Merge Request vorbereiten) selbständig aus.
  3. Konventionen werden eingehalten. Die Regeln zu Sprache, Dateinamen, Struktur und Schreibstil stehen in der Datei CLAUDE.md im Repository und werden von Claude Code automatisch beachtet.
  4. Nur Ideen reinchatten. Es reicht, der KI die inhaltliche Idee in eigenen Worten zu schildern („Ergänze beim Kassenwart einen Abschnitt zu Mitgliedsbeiträgen, der erklärt, dass diese zu Semesterbeginn eingezogen werden …"). Claude formuliert, strukturiert und baut es passend ein.

Vorgehen in Kurzform:

  1. Claude Code installieren. Einmalig lokal einrichten – Anleitung unter https://claude.com/claude-code.
  2. Repository klonen (siehe Abschnitt 4 „Vollständige Variante").
  3. Claude Code im Repo-Ordner starten und die gewünschten Änderungen im Chat beschreiben.
  4. Prüfen und freigeben. Vor jedem Commit zeigt Claude die Änderungen an – man bestätigt, was übernommen werden soll.

Wer lieber klassisch arbeiten möchte, kann die Dokumentation selbstverständlich auch komplett von Hand pflegen. Die folgenden Abschnitte beschreiben diese manuellen Wege.

3. Inhalte ändern – die einfache Variante (im Browser)

Für kleinere Korrekturen und Ergänzungen reicht der GitLab-Web-Editor aus; lokales Git-Setup ist nicht nötig.

  1. Datei öffnen. Zur gewünschten Datei im Ordner docs/ navigieren (z.B. docs/Kassenwart.md).
  2. Bearbeiten. Oben rechts auf Edit klicken und im Web-Editor die Markdown-Datei anpassen.
  3. Commit. Unten eine kurze, aussagekräftige Commit-Nachricht eingeben (z.B. „Kassenwart: Hinweis zu Mitgliedsbeiträgen ergänzt").
  4. Merge Request. Eine neue Branch anlegen (Standardvorschlag übernehmen) und einen Merge Request gegen main erstellen. Die Änderungen werden dort vom Vorstand geprüft und zusammengeführt.

Direkte Commits auf main sind in der Regel nicht möglich – main ist geschützt.

4. Inhalte ändern – die vollständige Variante (lokal mit Git)

Für umfangreichere Änderungen, insbesondere wenn mehrere Dateien gleichzeitig angepasst werden, empfiehlt sich lokales Arbeiten mit Git.

  1. Klonen. Das Repository lokal klonen: git clone https://gitlab.com/aachener-studentenorchester/documentation.git
  2. Branch. Eine neue Branch für die Änderung anlegen: git checkout -b mein-thema
  3. Vorschau (optional). Wer die Dokumentation lokal im Browser ansehen möchte, installiert MkDocs samt Material-Theme und startet den Entwicklungsserver: pip install mkdocs-material mkdocs serve Die Vorschau ist dann unter http://127.0.0.1:8000 erreichbar und aktualisiert sich bei jeder Dateiänderung automatisch.
  4. Commit und Push. Änderungen committen und auf GitLab pushen: git add docs/ git commit -m "Kurze Beschreibung der Änderung" git push -u origin mein-thema
  5. Merge Request. Auf GitLab einen Merge Request gegen main öffnen.

5. Konventionen

Damit die Dokumentation einheitlich bleibt, gelten ein paar Regeln:

  1. Sprache. Alle Inhalte werden auf Deutsch verfasst.
  2. Dateinamen. Dateinamen in PascalCase, z.B. Kassenwart.md oder StellvertretenderVorstandssprecher.md.
  3. Struktur von Aufgabendokumenten. Aufgabendokumente für Vorstandsposten folgen dem bestehenden Aufbau: Zweck des Dokuments → Aufgabenbereiche (nummeriert) → Noch zu dokumentieren.
  4. Schreibstil. Innerhalb der Aufgabenbereiche werden nummerierte Listen mit ausformulierten Sätzen verwendet, gerne mit fett gesetzten Lead-ins (z.B. **Buchungen überwachen.** Der Kassenwart behält …).
  5. Navigation. Neue Seiten werden in mkdocs.yml in die Navigation aufgenommen und ggf. auch von der Startseite (docs/index.md) aus verlinkt.

6. Veröffentlichung

Sobald ein Merge Request in main gemerged ist, startet automatisch die GitLab CI/CD-Pipeline. Die aktualisierte Dokumentation ist wenige Minuten später unter https://doku.aachener-studentenorchester.de/ erreichbar.