# Grundregeln für den Gebrauch von IssueZilla

### Warum Sie das lesen sollten

Stellen Sie sich vor, wieviele Leute später Ihr Issue lesen werden (das Issue, das Sie aufgegeben haben, oder an dem Sie teilnehmen).

- Community Mitglieder, die Probleme sichten
- Entwickler, die das Problem letztlich reparieren
- manchmal Entwickler, die im Vorfeld arbeiten
- QA Programmierer, die die Lösung verifizieren
- Alle anderen, die dasselbe Problem haben, und verstehen wollen, ob

- Ihr Problem auch sein/ihr Problem beschreibt
- oder ob sie für Ihr Issue stimmen sollten

- möglicherweise Mitglieder des Benutzererfahrung Teams, um Anforderungen für Zusatzfunktionen zu evaluieren
- möglicherweise ein Mitglied des Veröffentlichungsteams, um abzuschätzen, ob das Problem wichtig genug ist, um in ein Update wie 2.0.1 einzufließen

Sie sehen, es gibt eine Menge Leute, die lesen was Sie geschrieben haben. Deshalb konzentrieren sich die meisten Regeln auf die leichte Lesbarkeit: Ihre Einhaltung mag Ihnen manchmal ein wenig Zeit rauben, dafür sparen die Anderen später eine Menge Zeit.

Bitte versuchen Sie allen Anderen zu helfen, indem Sie sich an diese einfachen Regeln halten, und zwar nicht nur, wenn Sie ein Issue aufgeben, sondern auch wenn Sie Kommentare zu bestehenden Issues schreiben.
Da die Missachtung der Regeln die Behandlung des Problems erschwert (manchmal extrem erschwert), könnten sich die Anderen dafür entscheiden, Ihre Issues so lange zu ignorieren, bis sie auf vernünftige Weise bearbeitbar sind.

### Die Regeln

Für diejenigen, die es kurz und bündig mögen:

- Ein Problem - Ein Issue
- Erstellen Sie eine aussagekräftige Zusammenfassung
- Erstellen Sie eine Schritt-für-Schritt Beschreibung
- Stellen Sie wenn möglich Beispieldokumente zur Verfügung
- Verwenden Sie angemessene Anhänge

#### Ein Problem - Ein Issue

Bitte geben Sie für jedes Problem ein Issue auf. Dafür gibt es unterschiedliche Gründe, unter anderem sind das:

- Je mehr Fehler ein Issue beinhaltet, desto größer ist die Chance, einige mit der Zeit aus den Augen zu verlieren.
- Unterschiedliche Probleme werden höchstwahrscheinlich von verschiedenen Menschen bearbeitet (sowohl beim Programmieren, wo die Probleme gelöst, als auch in der Qualitätskontrolle, wo sie verifiziert werden). Je mehr Probleme Sie in ein Issue packen, desto schwerer ist seine Behandlung für alle Beteiligten.

Im Einzelnen bedeutet das, dass Sie sich ernsthaft fragen, ob Sie nicht mehrere Issues aufgeben sollten, bevor Sie Sätze wie "Ausserdem bemerkte ich..." oder "Es gibt verschiedene Probleme mit...".
Machen Sie sich darauf gefasst, dass Sie von den Anderen aufgefordert werden, Ihr Issue aufzuteilen.

#### Erstellen Sie eine aussagekräftige Zusammenfassung

Eine Menge Leute sind regelmäßig mit einer hohen Anzahl Issues befasst. Normalerweise geschieht das, wenn Berichte über Issues erstellt werden, die eine Zusammenfassung aller Issues plus einige zusätzliche Daten beinhalten. Daher ist die Zusammenfassung eines einzelnen Issues von sehr hoher Wichtigkeit: Sorgfältig formuliert erlaubt sie

- ein Issue in einer Liste dutzender anderer leicht zu erkennen
- ein Issue zu finden. Da doppelte Issues eine Menge Arbeit von engagierten Community Mitgliedern in Anspruch nehmen, motivieren wir immer alle, die ein Issue aufgeben wollen, zuerst nachzusehen, ob das Problem schon bekannt ist, und ein entsprechendes Issue aufgegeben wurde. Das funktioniert natürlich am Besten, wenn die einzelnen Beschreibungen wirklich aussagekräftig formuliert sind.
- die Wichtigkeit eines Issues zu beurteilen. "Problem mit Tabellenkalkulation" wird weniger gern behandelt werden, wie "Tabellenkalkulation: Datenverlust bei..." oder "Beschriftung X in Dialog Y hat falschen Abstand (2 Pixel)".

Deshalb vermeiden Sie bitte Zusammenfassungen wie "Großes Problem in OpenOffice.org" oder "Impress Problem" - sie helfen nicht wirklich, sondern nötigen die Anderen durch einzelne Issues zu browsen (statt sie in einem Bericht zu sehen) um den Inhalt zu sehen.

#### Erstellen Sie Schritt-für-Schritt Beschreibungen

Als Absender eines Issues wissen Sie ganz genau, was Sie getan haben, um auf Ihr Problem zu stossen. Die meisten Anderen wissen das wahrscheinlich nicht. Sie könnten eine völlig andere Herangehensweise haben, die selben Dinnge zu tun wie Sie.

Sogar unschuldige Phrasen wie "den Text fett formatieren" bergen Potential für Missverständnisse: Sie können fetten Text erhalten, indem Sie einen Stil zuweisen, indem Sie den Text markieren und auf den passenden Knopf in der Symbolleiste klicken, indem Sie "Stil|Fett" aus dem Kontextmenü wählen, über das Menü "Format|Zeichen" oder über "Zeichen" aus dem Kontextmenü und dem folgenden Dialog. Daher ist eine Beschreibung wie "Wenn ich versuche den Text fett zu formatieren stürzt OpenOffice.org ab" nutzlos, denn sie zwingt die Anderen nachzufragen, was Sie eigentlich gemeint haben.

Das mag ein triviales Beispiel sein, und Sie könnten argumentieren, dass es die Anderen ja nur versuchen müssten, um eventuell so darauf zu kommen, was Sie gemeint haben könnten. Aber es gibt Gründe, die dagegen sprechen:

- Auch wenn das Problem für Sie einfach erscheint, kann es tiefere Gründe geben, warum sich Leute gegen das Versuchen entscheiden. Sie könnten z.B. den "Fett" Knopf in einer selbst angepassten, nicht standardmässigen Symbolleiste verwendet haben, und die Versuche wären ohne Nutzen und Zeitverschwendung, denn niemand könnte Ihr Problem nachvollziehen.
- Genau aufzuschreiben, was Sie getan haben, kostet Sie einmal ein wenig Zeit, aber jeder Leser (und sie könnten im Laufe der Lebenszeit eines Issues zahlreich werden) braucht Zeit zum Raten und Ausprobieren. Es ist effizienter, wenn Sie diese Zeit investieren, damit sich QA und Programmierer auf die Lösung des Problems konzentrieren können, statt es erst sichten zu müssen.
- Es gibt viele Szenarien, die weit mehr Möglichkeiten beinhalten. Text fett zu formatieren mag leicht und einfach sein (Sie haben jedoch schon gelesen, dass es selbst dafür fünf verschiedene Möglichkeiten gibt), aber andere Aufgaben benötigen mehrere Schritte, die Sie unbedingt wissen, aber Ihre Leser nicht.

Vielleicht halten Sie folgende Beschreibung für unsinnig

- öffne ein neues Writer Dokument
- füge einen Beispieltext ein
- markiere den ganzen Text mit "Bearbeiten|Alles auswählen"
- wähle aus dem Kontextmenü des Textes "Stil|Fett"
- => OpenOffice.org stürzt ab

Es gibt durchaus Fälle, die eine so detaillierte Beschreibung überflüssig machen. Aber glauben Sie uns, in letzter Konsequenz spart sie weit mehr Zeit, als sie in Anspruch genommen hat.

#### Stellen Sie wenn möglich Beispieldokumente zur Verfügung

Falls Sie ein Problem mit einem bestimmten Dokument haben, erstellen Sie einen Anhang. Das erlaubt in den meisten Fällen ein einfaches reproduzieren Ihres Problems durch das Öffnen Ihre Anhangs.

Falls die Beschreibung Ihres Problems (siehe Erstellen Sie Schritt-für-Schritt Beschreibungen) sehr ausführlich ausfällt, könnten Sie in Erwägung ziehen, das Resultat der Beschreibung als Beispieldokument an Ihr Issue anzuhängen.

Oh, und noch etwas: Falls Sie ein Problem auf Seite 3 Ihrer 1000 Seiten langen Diplomarbeit haben, vergewissern Sie sich zuerst, dass es auch auftritt, wenn Sie Seite 3 von den anderen trennen. Falls ja, hängen Sie bitte Seite 3 an Ihren Issue, statt alle 1000 Seiten ...

#### Verwenden Sie angemessene Anhänge

Kopieren Sie bitte keine großen Dateien in die Beschreibung. Falls Sie z.B. aufgefordert werden, den Stapelspeicher eines Absturzes zur Verfügung zu stellen, kopieren Sie den Stapel zuerst in eine Datei, und hängen Sie diese dann an. Falls ein Makro in Basic oder Java Code ein Problem verursachen, kopieren Sie den Code in eine extra Datei und hängen diese dann an.

Das hat einen einfachen Grund: Eine drei Seiten lange Beschreibung macht das Lesen eines Issues sehr kompliziert. Alle, die nur einen ersten Eindruck gewinnen wollen, müssen in einer Riesenmenge Informationen stöbern, die zwar wirklich wichtig sein mögen, im Augenblick aber nur von peripherem Interesse für diese Menschen.

Der Author des Original Dokuments ist Frank Schönheit. Konstruktives Feedback ist willkommen. Eventuell wollen Sie die Mailing Liste besuchen, die sich mit diesen Themen beschäftigt. Übersetzung: Erich Christian

Last change: $Date: 2004/01/07 12:54:47 $ / $Author: fs $