Übergabe: Handbuch-Lücken-Analyse aus 24 Monaten Support-Daten

Dieses Dokument erklärt, was handbuch-luecken.md und die Cluster-Dateien in clusters/ sind, wie sie entstanden sind und wie man damit weiterarbeitet. Stand: 11. September 2026.

Worum es geht

Ziel der Analyse war herauszufinden, welche Hilfeartikel im Pentacode-Handbuch fehlen oder verbessert werden sollten — nicht auf Basis von Bauchgefühl, sondern auf Basis der tatsächlichen Support-Anfragen der letzten 24 Monate (September 2024 bis September 2026) aus der Help-Scout-Support-Inbox.

Das zentrale Ergebnis ist handbuch-luecken.md: eine nach Häufigkeit priorisierte Liste von Themen, zu denen Kunden immer wieder beim Support anfragen. 71 % aller echten Anfragen wurden bei der Auswertung als „durch einen Hilfeartikel beantwortbar" eingestuft — das ist das Potenzial, das mit besserer Dokumentation abgefangen werden könnte.

Wie die Daten entstanden sind

Die Auswertung lief in drei Schritten (Skripte und Anleitung siehe README.md; alle Schritte sind gegenüber Help Scout rein lesend):

1. Export (fetch-all.ts): Alle 6.346 Konversationen der Support-Inbox aus 24 Monaten wurden nach all-conversations.jsonl exportiert. Vor dem Schreiben auf die Festplatte wurden E-Mail-Adressen, Telefonnummern und IBANs durch Platzhalter ersetzt sowie zitierte Mail-Historien und Signaturen entfernt.

2. Extraktion (extract.ts): Jede Konversation wurde einmal von Claude (Anthropic API) gelesen. Pro Konversation wurden extrahiert: die enthaltenen Kundenfragen in kanonischer Form, der Themenbereich, die Support-Antwort als Zusammenfassung, der Antworttyp, ob das Anliegen gelöst wurde und ob die Frage durch einen Hilfeartikel beantwortbar wäre (handbuch_relevant). Ergebnis: extracted.jsonl. Dabei wurden 1.709 Konversationen als Rauschen aussortiert (Autoreplies, reine Rückrufbitten, Spam, Tests).

3. Clustering: Die verbleibenden 4.637 echten Anfragen enthielten 6.201 Einzelfragen (eine Mail kann mehrere Fragen enthalten). Inhaltlich gleiche Fragen wurden zu 736 Frage-Clustern zusammengefasst — z. B. landen „Wo finde ich den Code für die Stempeluhr?" und „Stempeluhr verlangt Verbindungscode, wo bekomme ich den her?" im selben Cluster. Die Cluster decken 5.608 der 6.201 Fragen ab; der Rest sind Einzelfragen ohne passendes Cluster.

Aus den Clustern wurden dann zwei Dokumente erzeugt:

• handbuch-luecken.md — die priorisierte Lückenliste (Erklärung unten)
• faq.md / faq.docx — ein FAQ-Entwurf mit allen Clustern inklusive der Antworten, die ausschließlich aus tatsächlichen Support-Antworten zusammengefasst wurden

Das Dokument handbuch-luecken.md

Das Dokument hat fünf Abschnitte. Die Aufteilung folgt der Frage: Was davon ist ein Handbuch-Thema, was ein Bug, was ein Produktwunsch?

1. Top-Kandidaten für neue oder bessere Hilfeartikel

Die 60 häufigsten Cluster, die als handbuch_relevant eingestuft wurden, sortiert nach Anzahl. Das ist die eigentliche Arbeitsliste für die Doku: Platz 1 (Fehlermeldung „Es existiert bereits eine Abwesenheit in diesem Zeitraum", 65 Anfragen) hat allein mehr Support-Aufwand verursacht als viele Bereiche zusammen. Insgesamt gibt es 531 handbuch-relevante Cluster; die 471 nicht in der Tabelle gezeigten (zusammen 2.849 Fragen) stehen in den Cluster-Dateien.

2. Wiederkehrende Fehlerbilder

Cluster vom Typ bug — Dinge, die aus Kundensicht kaputt sind oder waren (falsche Salden, PDFs laden nicht, Störungen). Kein Handbuch-Thema, aber relevante Support-Treiber und ggf. Input für die Entwicklung. Vorsicht: Die Daten reichen zwei Jahre zurück, einzelne Fehlerbilder können längst behoben sein.

3. Meistgefragte fehlende Funktionen

Cluster vom Typ funktion fehlt — wiederkehrende Wünsche wie eAU-Abruf, Urlaubssperre oder halbe Urlaubstage. Diese Fragen kommen wieder, solange die Funktion fehlt. Kandidaten für die Produkt-Roadmap oder für einen ehrlichen Artikel im Stil „geht derzeit so nicht, Workaround: …".

4. Häufige Fragen ohne dokumentierte Antwort

Cluster, bei denen der Support keine schriftliche inhaltliche Antwort gegeben hat (telefonisch gelöst oder offen geblieben). Für FAQ oder Handbuch muss die Antwort hier erst fachlich erarbeitet werden.

5. Kennzahlen

Die Eckdaten der Auswertung auf einen Blick:

• 6.346 Konversationen gesamt, davon 1.709 Rauschen
• 4.637 echte Anfragen → 6.201 Einzelfragen → 736 Cluster
• Antworttypen: 1.525 Erklärung, 562 Einstellung, 490 Support-Aktion, 426 Bug, 334 Workaround, 328 Funktion fehlt, 196 Weiterleitung, 776 ohne Antwort
• Oberflächen: 3.665 Verwaltung, 410 Mitarbeiter-App, 388 Stempeluhr
• 3.312 Anfragen (71 %) als „durch Hilfeartikel beantwortbar" eingestuft

Die Cluster-Dateien (clusters/*.json)

Die 21 JSON-Dateien sind die Rohdaten hinter beiden Dokumenten — eine Datei pro Themenbereich. Wer zu einer Zeile in handbuch-luecken.md mehr wissen will (Antwort, Beispielfälle), schaut hier nach.

Aufbau einer Cluster-Datei

Jede Datei enthält den Bereichsnamen, die Gesamtzahl der Fragen im Bereich und die Liste der Cluster:

{
  "bereich": "abwesenheiten",
  "gesamt": 704,
  "cluster": [
    {
      "frage": "Wie kann ich einen halben Urlaubs- oder Krankheitstag eintragen?",
      "anzahl": 31,
      "flaeche": "verwaltung",
      "typ": "workaround",
      "handbuch": true,
      "antwort": "Halbe Urlaubstage können derzeit nicht direkt gebucht werden; ...",
      "ids": [2735936001, 2779584055, ...]
    }
  ]
}

Bedeutung der Felder:

Die Antworttypen (typ):

Wichtige Hinweise und Einschränkungen

• Antworten sind unverifiziert. Die antwort-Texte fassen zusammen, was der Support tatsächlich geschrieben hat — sie können veraltet oder im Einzelfall falsch gewesen sein. Vor Übernahme ins Handbuch oder FAQ fachlich prüfen.
• Die Zählung ist eine Untergrenze pro Thema. Ähnliche Fragen können auf mehrere benachbarte Cluster verteilt sein (z. B. tauchen Sollstunden/Feiertage in mehreren Bereichen auf). Für die Priorisierung lohnt es sich, verwandte Cluster gedanklich zusammenzuziehen.
• Bugs können behoben sein. Abschnitt 2 blickt zwei Jahre zurück; vor Maßnahmen aktuellen Stand prüfen.
• Datenschutz: Die Rohdaten (all-conversations.jsonl, extracted.jsonl, export/) enthalten trotz Redaktion (E-Mails, Telefonnummern, IBANs ersetzt) weiterhin Namen im Fließtext. Nicht weitergeben; nur handbuch-luecken.md und faq.md sind für die interne Weitergabe gedacht.

Wie damit weiterarbeiten

1. Doku-Priorisierung: Abschnitt 1 von handbuch-luecken.md von oben nach unten abarbeiten. Pro Zeile: Cluster in der passenden clusters/*.json nachschlagen, antwort als inhaltlichen Ausgangspunkt nehmen, über die ids zwei bis drei Originalkonversationen in Help Scout lesen, um Formulierungen und Kontext der Kunden zu verstehen, dann Artikel schreiben oder überarbeiten.
2. FAQ: faq.md enthält bereits Antwortentwürfe zu allen Clustern — nach fachlicher Prüfung direkt verwendbar.
3. Produkt-Input: Abschnitt 3 (fehlende Funktionen) an das Produktteam geben; die anzahl liefert die Nachfrage-Evidenz.
4. Aktualisierung: Die gesamte Pipeline ist mit README.md reproduzierbar (fetch-all.ts → extract.ts → Cluster/Dokumente). Alle Schritte sind idempotent bzw. wiederaufnehmbar; benötigt werden Help-Scout-Zugangsdaten und ein Anthropic-API-Key in .env. Kosten der Extraktion: grob 5–8 € pro 1.000 Konversationen.