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:
Fallstudien wurden veröffentlicht. 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.

  • „Pull-Requests für unsere Onboarding-Dokumentation dauern zu lange, bis sie zusammengeführt werden. Die Mitwirkenden geben auf und verschwinden.“
  • „Wir haben zu viele Anfragen erhalten, bei denen Hilfe bei der Bedeutung von Fehlercodes benötigt wird.“
  • „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 Meetings schlecht gelaunt.“

Hypothese entwickeln

Suchen Sie nach Ursache und Wirkung. Was könnte die Ursache für das von Ihnen beschriebene Problem sein? 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. Prüfer verschieben die Überprüfung des PR entweder, weil sie nicht wissen, was sie tun sollen, oder sie tauschen sich mit den 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. Eine Sammlung von Klopf-Klopf-Witzen würde uns helfen, unsere Besprechungen mit einem Lächeln zu beginnen.“

Seien Sie konkret.

Können Sie das Problem quantifizieren?

  • „Was bedeutet es wirklich, dass es zu lange dauert, PRs zusammenzuführen? Zwei Monate? Zwei Wochen? Wie lange warten Mitwirkende auf die Überprüfung, bevor sie aufgeben?“
  • „Wie viele Fehlercode-bezogene Probleme 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 Mitwirkender aufgibt.“
  • „Wir können zählen, wie viele Probleme mit dem Tag ‚error-code‘ getaggt sind, oder innerhalb von Problemen nach dem Text des Fehlercodes suchen.“
  • „Wir können die Launenhaftigkeit von Menschen nicht wirklich auf taktvolle oder präzise Weise messen.“

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 sind der Meinung, dass zwei Wochen ein angemessener Zeitraum für die Zusammenführung kleiner bis mittelgroßer PRs sind. Alle PRs sollten innerhalb eines Monats zusammengeführt werden. Wir werden also alle zwei Wochen messen.“
  • „Es macht keinen Sinn, die Anzahl der Probleme im Zusammenhang mit Fehlercodes täglich zu aktualisieren, da es in der Regel eine Woche dauert, bis ein Problem geschlossen wird. Wir messen das wöchentlich.“

Ziele setzen

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

  • „Wenn wir unser Ziel erreichen, jeden neuen PR-Fall 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 sollten keine neuen fehlerbedingten Probleme auftreten. Wir würden unser Projekt jedoch als erfolgreich betrachten, wenn die Anzahl der offenen fehlerbedingten Probleme um 50% zurückgeht.“