Ein gutes GitHub-Issue lässt sich am besten schreiben, solange der Fehler noch auf dem Bildschirm steht. Die genaue Reihenfolge ist frisch. Die auffällige Konsolenzeile ist sichtbar. Sie wissen noch, welcher Workaround nicht geholfen hat und was sich seit dem letzten Release geändert hat.
Dann öffnen Sie den Issue-Editor, und aus dem Bericht wird: „Login funktioniert in Safari nicht.“
Spracheingabe hilft bei genau diesem Informationsverlust. Sie macht eine vage Beobachtung nicht automatisch präzise. Sie senkt die Hürde, Belege, Reihenfolge und Grenzen festzuhalten, die Sie bereits kennen, bevor alles auf Titel und einen Satz schrumpft.
GitHub-Issues können Fehler, Verbesserungen, Aufgaben und weitere Projektinformationen verfolgen. Der Text unterstützt GitHub Flavored Markdown mit Überschriften, Aufgabenlisten, Links und Codeblöcken. Ein Issue ist damit mehr als eine Nachricht. Es ist ein kleines Arbeitsprotokoll, das jemand anderes prüfen, reproduzieren und abschließen können sollte.
Die feste Struktur gehört in die Vorlage, die wechselnden Fakten in die Aufnahme
Die benötigten Abschnitte sind in vielen Teams bekannt:
- Zusammenfassung
- Schritte zur Reproduktion
- Erwartetes Ergebnis
- Tatsächliches Ergebnis
- Umgebung
- Abnahmekriterien
Diese Überschriften zu tippen ist nicht der teure Teil. Teuer ist, unter jeder Überschrift den Ablauf wieder zusammenzusetzen.
Praktisch ist eine Markdown-Issue-Vorlage im Repository, in die Sie nur die wechselnden Belege diktieren. GitHub unterstützt Markdown-Vorlagen und Issue-Formulare. Die stabilen Fragen können also schon sichtbar sein, wenn der Editor aufgeht. Ihre Stimme liefert die Fakten von heute: den vierten Klick, die Browser-Version, das alte Token, den unerwarteten Bildschirm und den Test, der nach der Korrektur bestehen soll.
Die Vorlage hält außerdem die Form. So wird aus der Aufnahme kein langer, unstrukturierter Bericht.
Reproduktionsschritte brauchen Reihenfolge und einen klaren Bruch
„Der Upload schlägt manchmal fehl“ lässt zu viel offen. Welche Datei? Welche Route? Vor oder nach der Anmeldung? Hilft ein erneuter Versuch? Was ist beim Fehler zu sehen?
Sprechen Sie die Schritte in Reihenfolge und markieren Sie den ersten Punkt, an dem das Verhalten abweicht:
- Beginnen Sie mit einem bekannten Ausgangszustand.
- Nennen Sie die Aktion.
- Sagen Sie, was nach wichtigen Aktionen erscheint.
- Stoppen Sie beim ersten falschen Ergebnis.
- Ergänzen Sie, ob sich der Fehler wiederholt.
Zum Beispiel:
Beginnen Sie mit einem angemeldeten Konto ohne Profilbild. Öffnen Sie die Einstellungen, wählen Sie eine PNG-Datei mit mehr als fünf Megabyte und drücken Sie einmal auf Speichern. Der Fortschrittsbalken erreicht hundert Prozent, danach erscheint ohne Fehlermeldung wieder der alte Avatar. Auch nach dem Neuladen ist das neue Bild nicht sichtbar. Mit einer kleineren PNG-Datei funktioniert derselbe Ablauf.
Der Absatz enthält einen Vergleichsfall, ein sichtbares Ergebnis und eine Aussage zur Wiederholbarkeit. Genau diese Details verschwinden oft, wenn der Bericht unter Zeitdruck getippt wird.
Beobachtung und Erklärung müssen getrennt bleiben
Ein Issue wird schwerer zu untersuchen, wenn eine Vermutung wie ein Beleg formuliert ist.
„Die Cache-Invalidierung ist kaputt“ kann stimmen, ist aber eine Diagnose. „Die zweite Anfrage liefert die alte Avatar-URL, nachdem der Upload-Endpunkt mit 200 geantwortet hat“ ist eine Beobachtung. Diese Aussage lässt sich prüfen, auch wenn die Ursache später an anderer Stelle gefunden wird.
Beim Diktieren helfen klare Markierungen:
- „Beobachtet habe ich …“ für sichtbares Verhalten.
- „Erwartet habe ich …“ für den angenommenen Vertrag.
- „Meine aktuelle Vermutung ist …“ für eine Hypothese.
- „Noch nicht geprüft ist …“ für eine offene Frage.
Beim Sprechen fließt eine Erklärung leicht in den Bericht ein. Als Hypothese gekennzeichnet bleibt sie nützlich, selbst wenn sie falsch ist.
Exakte Zeichen tippen, ihre Bedeutung diktieren
Für Chronologie und Begründung ist Sprache stark. Wenn jedes Zeichen zählt, ist sie schwächer.
Tippen oder kopieren Sie:
- Commit-Hashes und Issue-Nummern
- Dateipfade und Bezeichner
- URLs mit Query-Parametern
- Shell-Befehle und reguläre Ausdrücke
- Stacktraces und Log-Ausschnitte
- Versionsnummern, die sich nur in einer Ziffer unterscheiden
Logs und Code gehören in eingezäunte Codeblöcke, nicht in eine vorgelesene Paraphrase. GitHub rendert solche Blöcke und kann mit einer Sprachkennung Syntax hervorheben. Ein kurzer Originalausschnitt ist meist nützlicher, weil Leerzeichen, Satzzeichen und Zeilenfolge Belege tragen können.
Diktieren Sie anschließend den Zusammenhang: Woher stammt das Log, welche Aktion hat es erzeugt und welche Zeile ist wichtig? Die Tastatur bewahrt das Artefakt. Die Stimme bewahrt seine Bedeutung.
Abnahmekriterien schaffen einen überprüfbaren Endpunkt
Ein Issue kann den Fehler genau beschreiben und trotzdem schwer zu schließen sein. „Avatar-Upload reparieren“ sagt nicht, ob eine Fehlermeldung genügt, größere Dateien akzeptiert werden sollen, ein Retry nötig ist oder das neue Bild sofort erscheinen muss.
Fügen Sie Kriterien hinzu, die sich nach der Änderung prüfen lassen. GitHub-Aufgabenlisten verwenden Markdown-Checkboxen, sodass die Ergebnisse während der Arbeit sichtbar bleiben.
Für das Beispiel:
- Ein unterstütztes Bild zeigt den neuen Avatar ohne manuelles Neuladen.
- Eine nicht unterstützte Dateigröße erzeugt eine sichtbare Fehlermeldung.
- Ein fehlgeschlagener Upload ersetzt den vorhandenen Avatar nicht.
- Der Regressionstest deckt die fehlerhafte Größengrenze ab.
Beim Sprechen hilft eine direkte Frage: „Was müsste ich sehen, um die Korrektur zu akzeptieren?“ Die Liste sollte Ergebnisse beschreiben, nicht eine Umsetzung vorschreiben, sofern die Umsetzung selbst keine Anforderung ist.
Clean hält den Bericht treu, Raw hält die ganze Aufnahme
TalkTalkType nimmt auf, solange Sie Option-Leertaste halten, und gibt das Ergebnis an das zuvor fokussierte Feld zurück. Im GitHub-Issue-Editor bleiben Repository-Kontext, Vorlage und vorhandene Kommentare sichtbar, während Sie sprechen.
Clean führt eine treue, leichte Bereinigung durch. Es behält alle gesprochenen Wörter, ihre Reihenfolge, Ihr Register und die beabsichtigte Kürze. Entfernt werden nur eindeutige Zögerlaute; das Ergebnis kommt als eine Zeile zurück. Der Bericht wird nicht still in eine andere Vorlage verwandelt, und fehlende Fakten werden nicht erfunden.
Raw überspringt die Bereinigung und bewahrt die vollständige Transkription samt Fehlstarts. Das passt, wenn Sie stark nachbearbeiten oder einen ungewöhnlichen Eigennamen schützen möchten.
Keiner der Modi macht das Diktieren exakter technischer Zeichen zuverlässig. Lesen Sie den Entwurf vor dem Absenden und ersetzen Sie unsichere Versionen, Namen, Pfade und Zahlen durch kopierte Werte. Diktat, das in jeder App auf dem Mac funktioniert erklärt die Zustellung in das fokussierte Feld und den Zwischenablage-Fallback.
Bequeme Eingabe macht Geheimnisse nicht issue-tauglich
Ein Fehlerbericht kann in einem öffentlichen Repository, einem privaten Firmen-Repository oder einem später veröffentlichten Projekt landen. Das Ziel ist Teil der Datengrenze.
Sprechen Sie keine API-Schlüssel, Session-Cookies, Zugriffstoken, privaten Kundendaten oder Produktionszugänge. Schwärzen Sie auch eingefügte Logs. Spracheingabe reduziert den Aufwand, ändert aber nicht, wer das fertige Issue lesen kann.
TalkTalkType speichert Audio, Rohtranskripte und bereinigten Text nicht als serverseitigen Verlauf. Der fertige Text wird jedoch beim Erstellen des Issues an GitHub gesendet. Privates Diktat auf dem Mac verfolgt Aufnahme und Transkript durch die vorherigen Stationen.
Beginnen Sie mit dem Issue, das Sie sonst verschieben würden
Öffnen Sie die Repository-Vorlage, solange sich der Fehler noch reproduzieren lässt. Tippen Sie Titel und exakte Bezeichner. Diktieren Sie dann in einer Aufnahme Ausgangszustand, geordnete Aktionen, erstes falsches Ergebnis, Wiederholbarkeit, erwartetes Verhalten und offene Unsicherheit.
Lesen Sie den Text einmal. Fügen Sie den kleinsten nützlichen Log-Ausschnitt ein. Ergänzen Sie eine Checkliste, die den Abschluss definiert.
Das Ziel ist kein längeres Issue. Es soll genug von diesem Moment bewahren, damit jemand handeln kann, wenn der Moment vorbei ist.