Die richtigen Messwerte für Ihr Projekt auswählen

Dieser Leitfaden soll Organisationen helfen zu verstehen, welche Probleme durch eine bessere Dokumentation gelöst werden können und wie Sie geeignete Messwerte für Dokumentationsprojekte auswählen.

Aktuelle Phase:
Dokumentationsentwicklung. Siehe Zeitachse.

Beschreiben Sie Ihr Problem

Bevor Sie mit der Auswahl eines Messwerts beginnen, achten Sie darauf, dass Sie das Problem, das Sie lösen möchten, genau verstehen. Bitte sei so konkret wie möglich.

  • „Das Zusammenführen von Pull-Anfragen für unsere Onboarding-Dokumentation dauert zu lange. Die Beitragenden geben auf und gehen weg.“
  • „Es sind zu viele geöffnet, um die Fehlercodes besser verstehen zu können.“
  • „Unsere CI/CD-Pipeline ist instabil. Zu viele Tests schlagen aus schwer nachvollziehbaren Gründen fehl.“
  • „In unseren wöchentlichen Meetings sehen die Leute mürrisch aus.“

Eine Hypothese aufstellen

Suchen Sie nach Ursache und Wirkung. Was könnte die Ursache des von Ihnen genannten Problems sein? Beachten Sie, dass Probleme mehrere oder sich überschneidende Ursachen haben können.

  • „Es dauert so lange, Pull-Anfragen für die Onboarding-Dokumentation zusammenzuführen, da wir keine klaren Anweisungen zum Stil haben. Die Rezensenten schrecken entweder mit der Bewertung der PR ab, weil sie nicht wissen, was sie zu tun haben, oder sie gehen mit Beitragenden über die Formatierung hin und her.“
  • „Nutzer müssen Probleme öffnen, da sie keine Informationen zu Fehlercodes in der Dokumentation finden.“
  • „Unsere CI/CD-Tests schlagen fehl, da wir Tarifeinschränkungen und Zeitüberschreitungen bei unserem Anbieter haben.“
  • „In unseren wöchentlichen Meetings sind die Leute mürrisch, da die Meetings um 5:30 Uhr in ihrer Zeitzone stattfinden.“

Lösung vorschlagen

Könnte das Problem mit einer neuen oder besseren Dokumentation gelöst werden?

  • „Wenn wir einen Styleguide hätten, könnten Committer diesen prüfen, bevor sie ihre PRs einreichen. Die Prüfer wissen, worauf sie achten müssen. Bei Rezensenten und Beitragenden müssten sich keine Gedanken über Formatierung, Ton und Stil machen.“
  • „Wenn wir Dokumentationen über Fehlercodes hätten, konnten Nutzer dort ihre Antworten finden, anstatt Probleme zu öffnen.“
  • „Hmm, eine bessere Dokumentation würde unser CI/CD-Problem nicht lösen.“
  • „Wir könnten jedes Meeting mit einem Klopf-Witz beginnen! Wenn wir eine Sammlung von Witzen zusammenstellen, können wir unsere Meetings mit einem Lächeln beginnen.“

Genau anpassen

Können Sie das Problem quantifizieren?

  • Was bedeutet ‚Das Zusammenführen von PRs dauert zu lange‘ wirklich? Zwei Monate? Zwei Wochen? Wie lange warten Beitragende auf eine Rezension, bevor sie aufgeben?“
  • „Wie viele Probleme im Zusammenhang mit Fehlercodes sind ‚zu viele Probleme‘?“
  • „Hmmm... wie mürrisch ist ‚zu mürrisch‘?“

Messbarkeit prüfen

Wie würden Sie den vorgeschlagenen Messwert überprüfen? Lässt sie sich einfach und genau messen? Hängt die Messung davon ab, wer die Messung durchführt?

  • „Wir können ganz einfach messen, wie lange eine Pull-Anfrage offen ist und wie lange seit der Anforderung einer Überprüfung vergangen ist. Wir können nicht genau messen, wann eine Mitwirkende aufgibt.“
  • „Wir können zählen, wie viele Probleme mit 'Fehlercode' gekennzeichnet sind, oder in den Problemen nach Fehlercodetext suchen.“
  • „Wir können die Mäßigkeit bei den Menschen nicht wirklich taktisch oder genau messen.“

Sekundären Messwert hinzufügen

Gibt es andere Metriken, die Ihnen zeigen, ob Ihre Dokumentation Ihr Problem löst? Ist Ihr Zielmesswert in jedem Fall gleich?

  • „Längere PRs benötigen mehr Zeit für die Überprüfung. Wir sollten für verschiedene Größen von PRs unterschiedliche Grenzwerte festlegen. Wir wollen die Zeit für die Zusammenführung für kleine, mittlere, große und riesige PRs messen.“
  • „Wir könnten überprüfen, wie viele Besuche unsere Fehlercode-Dokumentation erhält, und feststellen, ob diese Zahl mit weniger offenen Problemen korreliert.“

Zeitraum auswählen

  • „Wir sind der Meinung, dass zwei Wochen eine angemessene Zeit sind, um kleine bis mittlere PRs zusammenzuführen. Alle PRs sollten innerhalb eines Monats zusammengeführt werden. Also messen wir alle zwei Wochen.“
  • „Es ist nicht sinnvoll, die Anzahl der fehlerbezogenen Probleme täglich zu aktualisieren, da wir normalerweise eine Woche zur Behebung eines Problems benötigen. Wir messen ihn wöchentlich.“

Ziele setzen

Welche Änderung müssten Sie an der ausgewählten Metrik vornehmen, um anzugeben, dass das Projekt ein Erfolg war? Legen Sie gegebenenfalls quantitative Ziele für die ausgewählten Metriken fest.

  • „Wenn wir unser Ziel erreichen würden, jede neue PR in weniger als einem Monat abzuschließen, wäre das ein Erfolg. Wenn die durchschnittliche Zeit zum Abschluss großer PRs um zwei Wochen kürzer wäre, wäre das ein großer Erfolg.“
  • „Im Idealfall würden wir keine neuen fehlerbezogenen Probleme sehen. Wir würden unser Projekt jedoch als erfolgreich bezeichnen, wenn die Zahl der fehlerbezogenen Probleme um 50% zurückgehen würde.“