Die richtigen Messwerte für Ihr Projekt auswählen

Dieser Leitfaden soll Organisationen dabei 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 Zeitplan.

Beschreiben Sie Ihr Problem.

Bevor Sie mit der Auswahl einer Metrik beginnen, sollten Sie sich mit dem Problem vertraut machen, das Sie lösen möchten. Bitte sei so konkret wie möglich.

  • „Das Zusammenführen der Pull-Anfragen für unsere Onboarding-Dokumentation dauert zu lange. Beitragende geben auf und gehen weg.“
  • „Uns sind zu viele Probleme offen, um die Fehlercodes besser verstehen zu können.“
  • „Unsere CI/CD-Pipeline ist instabil. Zu viele Tests schlagen aus unbekannten Gründen fehl.“
  • „Bei unseren wöchentlichen Meetings scheinen die Leute mürrisch zu sein.“

Eine Hypothese aufstellen

Suchen Sie nach Ursache und Wirkung. Woran könnte das von Ihnen erwähnte 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 Vorgaben zum Stil haben. Die Rezensenten schieben die PR ab, weil sie nicht wissen, was sie tun sollen, oder sie tauschen sich mit Beitragenden über Formatierungen aus.“
  • „Nutzer müssen Probleme öffnen, weil sie in der Dokumentation keine Informationen zu Fehlercodes finden.“
  • „Unsere CI/CD-Tests schlagen fehl, da bei unserem Anbieter Tarifbeschränkungen und Zeitüberschreitungen auftreten.“
  • „Bei unseren wöchentlichen Meetings sind die Leute mürrisch, da die Meetings um 05:30 Uhr ihrer Zeitzone stattfinden.“

Lösung vorschlagen

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

  • „Wenn es einen Styleguide gäbe, konnten unsere Commits diesen überprü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 mit Fehlercodes hätten, konnten Nutzer dort ihre Antworten finden, anstatt offene Fragen zu stellen.“
  • „Hmm, eine bessere Dokumentation würde unser CI/CD-Problem nicht lösen.“
  • „Wir könnten jedes Meeting mit einem Klopf-Witz starten! Wenn wir eine Sammlung von Witzen mit Kuckuck erstellt hätten, würden wir unsere Meetings mit einem Lächeln beginnen.“

Details

Können Sie das Problem quantifizieren?

  • „Was bedeutet es genau, PRs zusammenzuführen? 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 Ihren 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 leicht messen, wie lange eine Pull-Anfrage offen ist und wie lange seit der Anforderung einer Überprüfung eine Überprüfung dauert. Wir können nicht genau messen, wann ein Beitragender aufgibt.“
  • „Wir können zählen, wie viele Probleme mit 'Fehlercode' gekennzeichnet sind, oder in den Problemen nach Fehlercodetext suchen.“
  • „Wir können das Misstrauen der Menschen nicht wirklich taktisch oder genau messen.“

Sekundären Messwert hinzufügen

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

  • „Bei längeren PRs dauert die Überprüfung länger. Wir sollten für unterschiedliche Größen von PRs unterschiedliche Schwellenwerte haben. Wir möchten die Zeit für die Zusammenführung für kleine, mittlere, große und riesige PRs messen.“
  • „Wir konnten überprüfen, wie viele Besuche unsere Fehlercodedokumentation erhält, und feststellen, ob diese Zahl im Zusammenhang mit weniger offenen Problemen steht.“

Zeitraum auswählen

  • „Wir sind der Meinung, dass zwei Wochen eine angemessene Zeit für die Zusammenführung kleiner bis mittlerer PRs sind und alle PRs innerhalb eines Monats zusammengeführt werden sollten. Also messen wir alle zwei Wochen.“
  • „Es ist nicht sinnvoll, die Anzahl der Probleme im Zusammenhang mit Fehlercodes täglich zu aktualisieren, da wir normalerweise eine Woche benötigen, um ein Problem zu schließen. 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 für die ausgewählten Messwerte quantitative Ziele fest.

  • „Wenn wir unser Ziel erreichen würden, jeden neuen PR in weniger als einem Monat abzuschließen, wäre das ein Erfolg. Wenn sich unsere durchschnittliche Zeit bis zum Abschluss großer PRs um zwei Wochen verkürzen würde, wäre das ein großer Erfolg.“
  • „Im Idealfall treten keine neuen fehlerbezogenen Probleme auf. Aber wir würden unser Projekt als erfolgreich bezeichnen, wenn wir einen Rückgang von 50% bei fehlerbezogenen Problemen feststellen würden.“