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 Metriken für Dokumentationsprojekte auswählen.

Aktuelle Phase:
Ankündigung der Ergebnisse. Siehe Zeitachse.

Beschreiben Sie Ihr Problem

Bevor Sie mit der Auswahl einer Metrik beginnen, achten Sie darauf, dass Sie das Problem, das Sie zu lösen versuchen, genau verstanden haben. 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 gibt zu viele offene Fragen, um die Fehlercodes besser verstehen zu können.“
  • „Unsere CI/CD-Pipeline ist instabil. Zu viele Tests schlagen aus schwer nachvollziehbaren Gründen fehl.“
  • „Unsere wöchentlichen Meetings wirken mürrisch.“

Eine Hypothese aufstellen

Suchen Sie nach Ursache und Wirkung. Woran könnte das von Ihnen beschriebene Problem liegen? Denken Sie daran, 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 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 ihrer Zeitzone stattfinden.“

Lösung vorschlagen

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

  • „Wenn wir einen Styleguide haben, könnten unsere Committer diesen prüfen, bevor sie ihre PRs einreichen. Die Prüfer wissen, worauf sie achten müssen. Rezensenten und Beitragende müssen sich keine Gedanken über Formatierung, Ton und Stil machen.“
  • „Wenn wir Dokumentationen über Fehlercodes hätten, konnten die 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 Knock-Knock-Witz beginnen! Eine Sammlung von Witzen zu erstellen würde uns helfen, unsere Meetings mit einem Lächeln zu 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 müssen Beitragende auf eine Rezension warten, 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. 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 Misshandlung von 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 unterschiedliche 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 prü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 macht keinen Sinn, die Anzahl der fehlerbezogenen Probleme täglich zu aktualisieren, da wir normalerweise eine Woche benötigen, um ein Problem zu beheben. Wir messen ihn wöchentlich.“

Ziele setzen

Wie viele Änderungen müssten an der ausgewählten Metrik vorgenommen werden, um zu sagen, dass das Projekt ein Erfolg war? Legen Sie gegebenenfalls quantitative Ziele für die ausgewählten Messwerte fest.

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