Richtlinien zur Ticket- & Issue-Erstellung

Dieser Leitfaden bietet Best Practices für die Erstellung hochwertiger Tickets und Issues in unseren Ticketing-Systemen (YouTrack und Autotask).

Warum gute Tickets wichtig sind

Gut geschriebene Tickets:

• Sparen Zeit, indem sie alle notwendigen Informationen vorab bereitstellen
• Reduzieren Rückfragen und Kommunikationsaufwand
• Ermöglichen genaue Zeitschätzungen und Priorisierung
• Schaffen eine klare Dokumentation für zukünftige Referenz
• Helfen Teammitgliedern, den Kontext schnell zu verstehen

Anatomie eines guten Tickets

Jedes gute Ticket sollte diese Fragen beantworten:

1. Was ist das Problem oder die Anfrage?
2. Warum ist dies wichtig?
3. Wer ist betroffen?
4. Wann hat dies begonnen oder wann wird es benötigt?
5. Wo tritt dies auf (System, Umgebung, Ort)?
6. Wie kann dies reproduziert oder erreicht werden?

Effektive Titel schreiben

Ein guter Titel ist prägnant, aber beschreibend genug, um das Problem zu verstehen, ohne die vollständige Beschreibung lesen zu müssen.

Best Practices für Titel

Tun Sie:

• Beginnen Sie mit der betroffenen Komponente oder dem Modul: [MailManager] E-Mail-Domains können nicht gelöscht werden
• Verwenden Sie Aktionsverben: Beheben, Hinzufügen, Aktualisieren, Entfernen, Verbessern
• Seien Sie spezifisch: API gibt 500-Fehler zurück beim Erstellen von Autotask-Tickets ohne Priorität
• Halten Sie ihn unter 80 Zeichen, wenn möglich

Vermeiden Sie:

• Vage Formulierungen: Etwas ist kaputt ❌
• Nur generische Begriffe: Fehler im System ❌
• Lösungen im Titel: Datenbankfeld auf VARCHAR ändern ❌
• Großbuchstaben: DRINGEND REPARATUR BENÖTIGT ❌

Titel-Beispiele nach Typ

Bug-Reports:

✅ [YouTrack Sync] Zeiteinträge schlagen fehl bei Synchronisation wenn Beschreibung Sonderzeichen enthält
✅ Jamf Geräte-Synchronisation erstellt Duplikate für umbenannte Geräte
✅ School Tool DNS-Erstellung schlägt fehl für Domains mit Umlauten

Feature-Requests:

✅ Massen-E-Mail-Domain-Verwaltung zu MailManager hinzufügen
✅ Filterung nach Datumsbereich im Picking-Modul ermöglichen
✅ Automatische Wiederholung für fehlgeschlagene Autotask-API-Aufrufe implementieren

Support-Tickets:

✅ Kunde kann nach Domain-Migration nicht auf Postfach zugreifen
✅ Fehlende Rechnungen im BMD-Export für Oktober 2024
✅ Benutzer meldet Timeout beim Laden großer Gerätelisten

Tasks:

✅ Webhook-Handler auf neues Event-System migrieren
✅ AutoDNS-API-Integration auf v2 aktualisieren
✅ REST-API-Authentifizierungs-Endpunkte dokumentieren

Umfassende Beschreibungen schreiben

Die Beschreibung liefert den vollständigen Kontext und die Details, die zum Verstehen und Bearbeiten des Tickets erforderlich sind.

Struktur der Beschreibung

1. Zusammenfassung - Kurze Übersicht (1-2 Sätze)
2. Details - Vollständiger Kontext und relevante Informationen
3. Auswirkung - Wer/was ist betroffen und wie schwerwiegend
4. Zusätzlicher Kontext - Verwandte Tickets, Hintergrundinformationen, Einschränkungen

Erforderliche Informationen nach Typ

Bug-Reports

• Schritte zur Reproduktion - Nummerierte Liste exakter Schritte
• Erwartetes Verhalten - Was sollte passieren
• Tatsächliches Verhalten - Was tatsächlich passiert
• Umgebung - System, Browser, Version, Umgebung (dev/prod)
• Häufigkeit - Immer, manchmal, einmal (mit Bedingungen)
• Fehlermeldungen/Logs - Exakter Fehlertext oder relevante Log-Auszüge
• Screenshots - Visuelle Beweise, wenn zutreffend

Feature-Requests

• Anwendungsfall - Reales Szenario, warum dies benötigt wird
• Aktueller Workaround - Wie Benutzer dies derzeit handhaben (falls zutreffend)
• Lösungsvorschlag - Ihre Idee für die Implementierung (optional)
• Akzeptanzkriterien - Wie verifiziert wird, dass das Feature korrekt funktioniert
• Prioritätsbegründung - Warum dies priorisiert werden sollte

Support-Tickets

• Kunden-/Benutzerinformationen - Wer ist betroffen
• Problembeschreibung - Klare Erklärung des Problems
• Geschäftliche Auswirkung - Wie dies den Betrieb beeinflusst
• Dringlichkeit - Zeitrahmen und Kritikalität
• Durchgeführte Fehlersuche - Was bereits versucht wurde
• Kontaktinformationen - Wie betroffene Parteien erreicht werden können

Tasks/Arbeitspakete

• Ziel - Was erreicht werden muss
• Kontext - Warum diese Aufgabe existiert
• Akzeptanzkriterien - Definition von "Fertig"
• Abhängigkeiten - Blockiert von oder blockiert andere Tickets
• Aufwandsschätzung - Grobe Zeitschätzung (optional)
• Technische Hinweise - Implementierungsüberlegungen

Prioritäts- & Schweregrad-Richtlinien

Prioritätsstufen

Kritisch (P0)

• Produktionssystem ausgefallen
• Datenverlust oder -beschädigung
• Aktiv ausgenutztes Sicherheitsproblem
• Vollständiger Geschäftsstillstand
• Reaktionszeit: Sofort

Hoch (P1)

• Hauptfunktionalität für mehrere Benutzer ausgefallen
• Workaround existiert, ist aber schwierig
• Erhebliche geschäftliche Auswirkung
• Reaktionszeit: Am selben Tag

Mittel (P2)

• Feature funktioniert nicht wie vorgesehen
• Betrifft einige Benutzer oder Workflows
• Angemessener Workaround verfügbar
• Reaktionszeit: Innerhalb 1 Woche

Niedrig (P3)

• Kleine Probleme, kosmetische Fehler
• Nice-to-have Verbesserungen
• Minimale geschäftliche Auswirkung
• Reaktionszeit: Wenn Kapazität vorhanden

Schweregrad vs. Priorität

• Schweregrad = Technische Auswirkung (Wie kaputt ist es?)
• Priorität = Geschäftliche Dringlichkeit (Wie schnell muss es behoben werden?)

Beispiel: Ein Tippfehler in einer kundensichtbaren Oberfläche kann niedrigen Schweregrad, aber hohe Priorität haben, wenn er die Markenwahrnehmung beeinträchtigt.

Labels und Kategorien

Verwenden Sie Labels zur Verbesserung der Ticket-Organisation und Filterung.

TIP

Für YouTrack-Projekte siehe die detaillierten YouTrack Tags & Zeiterfassung Richtlinien mit standardisierten Tags über alle Projekte.

Systemspezifische Richtlinien

YouTrack

YouTrack ist unser primäres System für Entwicklungsarbeit und internes Issue-Tracking.

Best Practices:

• Verwenden Sie projektspezifische Workflows
• Verknüpfen Sie verwandte Issues mit passenden Link-Typen
• Fügen Sie Zeiteinträge hinzu, während Sie arbeiten
• Verwenden Sie Subsysteme zur Kategorisierung nach Modul
• @erwähnen Sie Teammitglieder bei Fragen
• Zeiteinträge synchronisieren automatisch mit Autotask

Benutzerdefinierte Felder:

• Autotask Ticket - Zur automatischen Übertragung der Zeiten ins Autotask

Autotask

Autotask wird für kundenseitige Tickets und Projektmanagement verwendet.

Best Practices:

• Immer mit einem Kunden/Firma verknüpfen
• Passende Ticket-Kategorie und Issue-Typ setzen
• Ticket-Queues für korrektes Routing verwenden
• Interne Notizen für Team-Kommunikation hinzufügen
• Zeiteinträge mit korrekten Arbeitstypen hinzufügen
• Mit verwandten Tickets, Projekten oder Verträgen verknüpfen

Pflichtfelder:

• Company - Kundenorganisation
• Title - Klare, kundengerechte Beschreibung
• Issue Type - Incident, Service Request, etc.
• Priority - Basierend auf SLA-Anforderungen
• Queue - Passende Routing-Queue

Beispiele: Gute vs. Schlechte Tickets

Beispiel 1: Bug-Report

Schlecht:

Titel: Sync funktioniert nicht
Beschreibung: Die Synchronisation ist kaputt, bitte so schnell wie möglich reparieren

Gut:

Titel: [YouTrack Sync] Zeiteinträge schlagen bei Synchronisation fehl wenn Beschreibung 500 Zeichen überschreitet

Beschreibung:
**Zusammenfassung**
Zeiteinträge mit Beschreibungen länger als 500 Zeichen schlagen bei der Synchronisation
von YouTrack zu Autotask fehl, was zu fehlenden abrechenbaren Zeiten führt.

**Schritte zur Reproduktion**
1. Erstellen Sie ein Work Item in YouTrack
2. Fügen Sie einen Zeiteintrag mit einer Beschreibung >500 Zeichen hinzu
3. Warten Sie auf automatische Synchronisation (oder lösen Sie manuelle Synchronisation aus)
4. Überprüfen Sie Autotask auf den Zeiteintrag

**Erwartetes Verhalten**
Zeiteintrag sollte erfolgreich synchronisiert werden, mit Beschreibung bei Bedarf gekürzt mit Hinweis.

**Tatsächliches Verhalten**
Synchronisation schlägt stillschweigend fehl. Eintrag erscheint im Sync-Log mit Fehler:
"Description field exceeds maximum length"
Zeiteintrag wird nicht in Autotask erstellt.

**Auswirkung**
- Betrifft 3-4 Zeiteinträge pro Woche
- Führt zu fehlenden abrechenbaren Stunden
- Erfordert manuelle Eingabe in Autotask

**Umgebung**
- Production (yt.iteas.cloud → integrations.iteas.cloud)
- YouTrack 2024.3
- Autotask API v1.6

**Fehler-Log**
[2024-10-26 14:23:41] Error syncing time entry YT-1234:
AutotaskClient\Exception: Field 'Description' maximum length is 500 characters

Beispiel 2: Feature-Request

Schlecht:

Titel: Bessere E-Mail-Verwaltung
Beschreibung: Wir brauchen bessere E-Mail-Verwaltungsfunktionen

Gut:

Titel: Massen-Domain-Verwaltung zu MailManager hinzufügen

Beschreibung:
**Anwendungsfall**
Beim Onboarding neuer Kunden mit mehreren E-Mail-Domains (5-10 Domains)
müssen wir derzeit jede Domain einzeln erstellen. Dies ist zeitaufwendig
und fehleranfällig.

**Aktueller Workaround**
Manuelle Erstellung von Domains einzeln über die MailManager-Oberfläche,
dauert ca. 2-3 Minuten pro Domain.

**Lösungsvorschlag**
Massen-Import-Feature hinzufügen, das akzeptiert:
- CSV-Upload mit Spalten: domain, customer_id, routing_type
- Oder Textbereich zum Einfügen mehrerer Domains (eine pro Zeile)
- Validierung vor Import mit Fehlerberichterstattung

**Akzeptanzkriterien**
- [ ] Kann mehrere Domains via CSV importieren
- [ ] Kann mehrere Domains via Texteingabe importieren
- [ ] Validierung erkennt Fehler vor Erstellung von Domains
- [ ] Erfolgs-/Fehlerbericht nach Import
- [ ] Fehlgeschlagene Imports blockieren erfolgreiche nicht
- [ ] Alle bestehenden Domain-Validierungsregeln gelten

Beispiel 3: Support-Ticket

Schlecht:

Titel: Kundenbeschwerde
Beschreibung: Kunde sagt, etwas stimmt nicht mit ihrer E-Mail

Gut:

Titel: [Kunde: Acme Corp] Kann keine E-Mails auf support@acme.at empfangen

Beschreibung:
**Kundeninformationen**
- Firma: Acme Corp (ID: AT-12345)
- Kontakt: Maria Schmidt (maria@acme.at, +43 123 456789)
- Domain: acme.at
- Betroffenes Postfach: support@acme.at

**Problembeschreibung**
Kunde meldet, dass das Postfach support@acme.at seit gestern (2024-10-25)
um ca. 16:00 CET keine E-Mails mehr empfängt. Absender erhalten keine
Bounce-Meldungen; E-Mails scheinen stillschweigend verworfen zu werden.

**Geschäftliche Auswirkung**
- Kritisches Business-Postfach für Kundensupport
- Ca. 50 Support-Anfragen pro Tag erwartet
- Kundengeschäft ist betroffen, da sie nicht auf Support-Anfragen antworten können
- SLA: 4-Stunden-Reaktionszeit gilt

**Durchgeführte Fehlersuche**
- DNS-Einträge der Domain verifiziert (MX, SPF, DKIM) - korrekt
- Mailgun-Dashboard überprüft - keine Zustellversuche sichtbar
- Test-E-Mail von privatem Account gesendet - nicht empfangen
- Spam-Ordner überprüft - leer
- Postfach-Quota verifiziert - nicht überschritten

**Zeitplan**
- Letzte erfolgreiche E-Mail empfangen: 2024-10-25 15:47 CET
- Problem gemeldet: 2024-10-26 09:15 CET
- Erforderliche Lösung: Heute (innerhalb SLA)

**Zusätzlicher Kontext**
- Keine kürzlichen Änderungen an E-Mail-Konfiguration
- Andere Postfächer auf derselben Domain funktionieren korrekt
- Kunde hat wichtige Kunden-Deadline heute, die E-Mail-Zugang erfordert

Checkliste vor Absenden

Vor Erstellung Ihres Tickets überprüfen Sie:

• [ ] Titel beschreibt Problem klar in unter 80 Zeichen
• [ ] Alle erforderlichen Informationen für Ticket-Typ sind enthalten
• [ ] Schritte zur Reproduktion sind klar und nummeriert (bei Bugs)
• [ ] Priorität/Schweregrad ist angemessen und begründet
• [ ] Relevante Labels/Kategorien sind angewendet
• [ ] Verwandte Tickets sind verknüpft
• [ ] Screenshots oder Logs sind angehängt, falls zutreffend
• [ ] Kunde/Firma ist verknüpft (bei Autotask)
• [ ] Subsystem ist gesetzt (bei YouTrack)
• [ ] Zuständiger ist gesetzt, falls bekannt (sonst für Triage offen lassen)

Hilfe bekommen

Wenn Sie unsicher sind über:

• Prioritätsstufe - Fragen Sie Ihren Teamleiter oder Manager
• Welches System zu verwenden - Entwicklungsarbeit → YouTrack, Kundenprobleme → Autotask
• Technische Details - Sammeln Sie so viele Informationen wie möglich, notieren Sie, was Sie nicht wissen
• Wer es bearbeiten sollte - Erstellen Sie das Ticket und lassen Sie es durch Triage zuweisen

Zusätzliche Ressourcen

• Ticket-Vorlagen - Sofort kopierbare Vorlagen
• YouTrack Tags & Zeiterfassung - Standardisierte Tags und Arbeitstypen
• YouTrack - Zugriff auf YouTrack-System
• CLAUDE.md - Entwicklungsdokumentation