Die richtigen Messwerte für Ihr Projekt auswählen

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

Aktuelle Phase:
Das Docs-Programm 2021 endete am 14. Dezember 2021. Siehe Zeitachse.

Problem beschreiben

Bevor Sie sich für einen Messwert entscheiden, sollten Sie sich ein genaues Bild von dem Problem machen, das Sie lösen möchten. Bitte sei so konkret wie möglich.

  • „Das Zusammenführen von Pull-Anfragen für unsere Onboarding-Dokumentation dauert zu lange. Die Mitwirkenden geben auf und verschwinden wieder.“
  • „Wir erhalten zu viele Anfragen, bei denen wir Hilfe beim Verständnis von Fehlercodes benötigen.“
  • „Unsere CI/CD-Pipeline ist unzuverlässig. Zu viele Tests schlagen aus nicht genau bekannten Gründen fehl.“
  • „Die Leute wirken in unseren wöchentlichen Besprechungen mürrisch.“

Hypothese entwickeln

Suchen Sie nach Ursache und Wirkung. Woran könnte das von Ihnen beschriebene Problem liegen? Beachten Sie, dass Probleme mehrere oder sich überschneidende Ursachen haben können.

  • „Es dauert so lange, Pull-Requests für die Onboarding-Dokumentation zusammenzuführen, weil wir keine klaren Richtlinien zum Stil haben. Die Rezensenten ziehen die PR entweder zurück, weil sie nicht wissen, was sie tun sollen, oder sie tauschen sich mit Mitwirkenden über die Formatierung aus.“
  • „Nutzer müssen Probleme melden, weil sie in der Dokumentation keine Informationen zu Fehlercodes finden.“
  • „Unsere CI/CD-Tests schlagen fehl, weil wir auf Planeinschränkungen und Zeitüberschreitungen unseres Anbieters stoßen.“
  • „Die Leute sind in unseren wöchentlichen Videokonferenzen schlecht gelaunt, weil sie in ihrer Zeitzone um 5:30 Uhr morgens stattfinden.“

Lösung vorschlagen

Könnte das Problem durch neue oder bessere Dokumentation gelöst werden?

  • „Wenn wir einen Styleguide hätten, könnten Committer ihn prüfen, bevor sie ihre PRs einreichen. Prüfer wüssten dann, worauf sie achten müssen. Rezensenten und Mitwirkende müssten sich nicht über Formatierung, Ton und Stil streiten.“
  • „Wenn wir eine Fehlercodedokumentation hätten, könnten Nutzer dort ihre Antworten finden, anstatt Probleme zu melden.“
  • „Hmm, es sieht nicht so aus, als würde eine bessere Dokumentation unser CI/CD-Problem lösen.“
  • „Wir könnten jede Besprechung mit einem Klopf-Klopf-Witz beginnen. Die Erstellung einer Sammlung von Klopfwitzen würde uns helfen, unsere Meetings mit einem Lächeln zu beginnen.“

Machen Sie konkrete Angaben

Können Sie das Problem quantifizieren?

  • „Was bedeutet „Es dauert zu lange, PR-Kampagnen zusammenzuführen“? Zwei Monate? Zwei Wochen? Wie lange warten Mitwirkende auf die Überprüfung, bevor sie aufgeben?“
  • „Wie viele Probleme mit Fehlercodes sind ‚zu viele Probleme‘?“
  • „Hmmm… wie mürrisch ist ‚zu mürrisch‘?“

Messbarkeit prüfen

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

  • „Wir können ganz einfach messen, wie lange ein Pull-Request offen ist und wie lange es her ist, dass eine Überprüfung beantragt wurde. Wir können nicht genau messen, wann ein Beitragender aufgibt.“
  • „Wir können zählen, wie viele Probleme mit ‚Fehlercode‘ gekennzeichnet sind, oder in Problemen nach Fehlercodetext suchen.“
  • „Wir können nicht genau messen, wie mürrisch die Leute sind.“

Sekundären Messwert hinzufügen

Gibt es noch andere Messwerte, die Ihnen helfen würden zu verstehen, ob Ihre Dokumentation das Problem löst? Ist Ihr Zielmesswert in jedem Fall gleich?

  • „Die Überprüfung längerer PRs dauert länger. Wir sollten unterschiedliche Grenzwerte für unterschiedliche Größen von PRs haben. Wir möchten die Zeit bis zur Zusammenführung für kleine, mittlere, große und riesige PRs messen.“
  • „Wir könnten prüfen, wie viele Zugriffe unsere Dokumentation zu Fehlercodes erhält, und sehen, ob diese Zahl mit weniger offenen Problemen korreliert.“

Zeitraum auswählen

  • „Wir halten zwei Wochen für einen angemessenen Zeitraum, um kleine bis mittlere PRs zusammenzuführen. Alle PRs sollten innerhalb eines Monats zusammengeführt werden. Wir werden also alle zwei Wochen messen.“
  • „Es macht keinen Sinn, die Anzahl der Probleme mit Fehlercodes täglich zu aktualisieren, da wir ein Problem in der Regel innerhalb einer Woche schließen. Wir messen ihn wöchentlich.“

Ziele setzen

Wie groß müsste die Veränderung bei der ausgewählten Messgröße sein, damit Sie sagen können, dass das Projekt ein Erfolg war? Legen Sie für die ausgewählten Messwerte quantitative Ziele fest.

  • „Wenn wir unser Ziel erreicht hätten, jede neue PR in weniger als einem Monat abzuschließen, wäre das ein Erfolg. Wenn sich die durchschnittliche Zeit für die Schließung großer PRs um zwei Wochen verkürzt, wäre das ein großer Erfolg.“
  • „Im Idealfall treten keine neuen fehlerbedingten Probleme auf. Wir würden unser Projekt jedoch als erfolgreich betrachten, wenn wir einen Rückgang der Anzahl der gemeldeten fehlerbezogenen Probleme um 50% verzeichnen würden.“