Im ersten Teil des Berichts haben wir dargelegt, wie die Qualität der Dokumentation und die Wirksamkeit ihrer Entwicklung gemessen werden können. Tauchen Sie nun in die Details des Zählens von Metriken ein.
Sagt Yuri Nikulin, Leiter des Entwicklungsdienstes für technische Dokumentation.
Definieren wir zunächst die Leistung. Im klassischen Sinne ist dies die Zeit, die benötigt wird, um eine Ausgabeeinheit zu produzieren, oder die Menge der Ausgabe, die pro Zeiteinheit erzeugt wird .
Dies ist beispielsweise die Anzahl der pro Monat produzierten Telefone oder die Zeit, die für die Herstellung von Tausenden von Telefonen benötigt wird. Es stellt sich die Frage, wie die intellektuelle Arbeit unserer Abteilung gemessen werden kann.
Wenn wir den klassischen Ansatz zur Bewertung der Produktivität anwenden, können wir berechnen, wie viele Dokumente, Seiten oder Wörter pro Tag, Woche und Monat geschrieben werden. Dies wird dazu beitragen, die potenzielle Zeit für die Erstellung von Dokumentationen in der Zukunft abzuschätzen, wird jedoch die Frage nach der Produktivität nicht beantworten. Schließlich sind wir definitiv nicht daran interessiert, die Effektivität von Schriftstellern anhand der Anzahl der von ihnen geschriebenen Wörter zu bewerten. Daher haben wir beschlossen, mit den Anforderungen für die Metriken zu beginnen, die wir zählen wollten.
Wir haben verschiedene Kriterien für die Auswahl von Metriken identifiziert:
- Transparenz Der Ansatz zur Berechnung von Metriken und zur Interpretation der Ergebnisse sollte nicht nur uns, sondern auch den Kunden klar sein.
- Datenverfügbarkeit. Einschließen von Daten für einen vergangenen Zeitraum, um Hypothesen aufzustellen und diese mit historischen Daten zu bestätigen.
- Möglichkeit zur Automatisierung des Zählens. Wir möchten Metriken definitiv nicht von Hand zählen.
Als Ergebnis haben wir erkannt, dass das ideale Objekt für die Berechnung von Leistungsmetriken die Aufgabe im Tracker ist. Es erfüllt alle Anforderungen, die wir an Metriken stellen.
Die Datenquelle für uns war Yandex.Tracker. Es ist sehr flexibel und leicht an unsere Aufgaben anpassbar. Es verfügt bereits über alle erforderlichen Daten, da wir dieses Tool jeden Tag verwenden. Der Tracker verfügt außerdem über eine API, mit der Sie diese Informationen verwenden und Prozesse automatisieren können.
Wir hatten also einen Plan, wie wir vorgehen sollten.
Richten Sie Warteschlangen und Aufgaben ein
Sie müssen zunächst die Warteschlangen, die Hierarchie der Aufgaben, ihre Typen und Status auswählen.
Dies wurde von Katya Kunenko im Bericht „ Tools zur Erstellung von Benutzerdokumentationen “ ausführlich beschrieben. Wir werden kurz über Warteschlangen und Aufgaben sprechen, die wir selbst verwenden.
Warteschlangen
Wir haben drei Zeilen, die im Wesentlichen unsere Zielgruppe widerspiegeln.
Aufgabenhierarchie
Unsere Aufgaben haben eine zweistufige Struktur:
- Auf der obersten Ebene entsprechen die Aufgaben veröffentlichten Dokumenten.
- Auf der unteren Ebene entsprechen die Aufgaben der Arbeit am Dokument.
Arten und Status von Aufgaben
Arten und Status von Aufgaben ermöglichen es uns nicht nur, Arbeitstypen und ihren aktuellen Status zu klassifizieren, sondern auch unsere Metriken mit Abschnitten zu berücksichtigen.
Zeitleiste für die Erledigung von Aufgaben. Die blaue Linie ist die durchschnittliche Produktionszeit des Dokuments, die orange Linie ist die Zeit, um den Fehler zu beheben, die grüne Linie ist die durchschnittliche Zeit, um Aufgaben aller Art zu erledigen.
Wir werden an einem Beispiel eines Diagramms erzählen. Zum Beispiel wird ein Fehler innerhalb von 1-5 Tagen behoben und es dauert 30-40, um ein neues Dokument zu schreiben. Gleichzeitig schreiben wir seltener neue Dokumente als die alten oder korrigieren Fehler. Daher ist die durchschnittliche Ausführungszeit einer Aufgabe eines beliebigen Typs (grüne Linie) für Fehler zu lang und für neue Dokumente zu kurz. Mit seiner Hilfe erhalten wir nur eine durchschnittliche Vorstellung davon, wie schnell Probleme gelöst werden können.
Da wir Metriken berücksichtigen, um Prozesse zu optimieren, müssen wir uns genauere Abschnitte ansehen: Zum Beispiel, wie lange wir das Problem „Fehler“ oder „neues Dokument“ lösen. Der Durchschnitt aller Typen kann angezeigt werden, um den Gesamttrend zu verfolgen.
Wir verwenden eine solche Reihe von Arten von Aufgaben.
Es gibt mehr Status als Typen, da der Workflow dies erfordert.
Es ist einfacher, mit Typen und Status zu arbeiten, wenn sie eindeutig sind und nicht zu viele vorhanden sind. Andernfalls können die Darsteller verwirrt werden.
So berücksichtigen Sie Leistungsmetriken
Im letzten Teil haben wir eine Studie durchgeführt und 20 von 136 Dokumentationsmetriken ausgewählt. Sechs davon sind Leistungsmetriken.
Das Zählen von Metriken hat zwei Aspekte.
- Aufgeschnittene Metriken zählen. Oben haben wir gesagt, was es ist und warum es uns wichtig ist.
- Gemittelte Werte zählen.
Der klassische Ansatz zur Berechnung von Durchschnittswerten besteht darin, alle Indikatoren zusammenzufassen und durch ihre Anzahl zu dividieren. Dieser Ansatz funktioniert nicht immer gut, da er entartete Fälle berücksichtigt. Zum Beispiel wissen wir, dass die meisten Fehler an einem Tag behoben werden. Es gibt jedoch entartete Fälle - zum Beispiel, wenn ein Ticket verloren geht oder ein Mitarbeiter kündigt -, dann dauert die Behebung länger. Angenommen, wir hatten im Berichtszeitraum sechs Fehler. Wir haben uns für fünf an einem Tag und einen für 115 entschieden. Es stellt sich heraus, dass die durchschnittliche Fehlerbehebung 20 Tage beträgt. Diese Zahl spiegelt jedoch nicht die Realität wider: Wir korrigieren fast immer Fehler für den Tag, und ein langes Ticket beeinflusst diesen Indikator erheblich.
In solchen Fällen kommt das Perzentil zur Rettung. Dies ist der Maximalwert (in unserem Fall Metriken), der dem angegebenen Prozentsatz der Objekte entspricht. Das 80. Perzentil ist beispielsweise ein Wert, der 80% der Objekte in der Stichprobe nicht überschreitet. In unserem Fall wäre ein solcher Wert ein Wert von 1, da 83% der Objekte ihn nicht überschreiten.
Hier erscheint die dritte Ebene - die Zeit, für die wir die Metriken zählen. Fast alle unsere Metriken zählen in 30 Tagen.
Wir betrachten Metriken mit Kürzungen wie folgt:
- zuerst alle Zeilen zusammen,
- dann schneiden wir abwechselnd
- Dann gehen wir ins Detail: Wir schneiden in Warteschlangen mit einem Schnitt für alle Arten von Aufgaben.
Jeder nachfolgende Abschnitt der Metrik verfeinert den vorherigen. Der Durchschnittswert für alle Warteschlangen, Typen und Status von Aufgaben gibt eine allgemeine Vorstellung. Wir betrachten dann den Wert für die einzelnen Warteschlangen, um zu verstehen, wie die Dinge mit der technischen, Benutzer- oder internen Dokumentation aussehen. Auf der letzten, detailliertesten Ebene arbeiten wir an einer Zeile „Warteschlange + Typ und Status“.
Weiter werden wir erklären, wie wir Leistungsmetriken berücksichtigen.
Anzahl der geschlossenen Aufgaben
Wie wir betrachten: nach der Anzahl der Aufgaben, die in dem Intervall geschlossen wurden [vor 31 Tagen; gestern].
Die Anzahl der in Arbeit genommenen Aufgaben
Wie wir betrachten: nach der Anzahl der Aufgaben, für die der Arbeitsbeginn in dem Intervall liegt [vor 31 Tagen; gestern].
Die Anzahl der Tage vor der Einstellung
Wie wir betrachten:
- Für jede Aufgabe, die im angegebenen Zeitraum (Startdatum im Tracker im Intervall [vor 31 Tagen; gestern]) ausgeführt wurde, berücksichtigen wir die Anzahl der vollen Tage, die zwischen der Anweisung (Felderstellungsdatum) und dem Start der Aufgabe (Feldstartdatum) vergangen sind. .
- Wir fassen alle im ersten Schritt erhaltenen Werte zusammen.
- Wir teilen den erhaltenen Betrag durch die Anzahl der Aufgaben, für die wir den ersten Artikel ausgeführt haben.
Bei Perzentilen wird Punkt 3 weggelassen, die Werte werden in aufsteigender Reihenfolge sortiert und der Wert ausgewählt, der dem angegebenen Perzentil entspricht.
Anzahl der Tage bis zum Abschluss
Wie wir überlegen.
- Für jede Aufgabe, die im angegebenen Zeitraum abgeschlossen wurde (Enddatum im Tracker im Intervall [vor 31 Tagen; gestern]), berücksichtigen wir die Anzahl der vollen Tage, die zwischen dem Arbeitsbeginn (Feldstartdatum) und der Aufgabe (Feldenddatum) vergangen sind.
- Wir fassen alle im ersten Schritt erhaltenen Werte zusammen.
- Wir teilen den erhaltenen Betrag durch die Anzahl der Aufgaben, für die wir den ersten Artikel ausgeführt haben.
Bei Perzentilen wird Punkt 3 weggelassen, die Werte werden in aufsteigender Reihenfolge sortiert und der Wert ausgewählt, der dem angegebenen Perzentil entspricht.
Die Anzahl der Aufgaben ohne Reaktion mehr als 14 Tage
Wie wir glauben: durch die Anzahl der Aufgaben, bei denen länger als 14 Tage nichts passiert ist. Dies wird durch das aktualisierte Feld im Tracker bestimmt: Der Feldwert sollte kleiner als "gestern - 14 Tage" sein.
Technische Schulden
Wie wir betrachten: durch die Anzahl der Aufgaben, für die der Backlog-Status im Tracker festgelegt ist.
Technische Implementierung der Leistungsmetrikberechnung
Auf der obersten Ebene besteht das Metrikzählsystem aus den folgenden Komponenten und Informationsverknüpfungen.
Geplantes Metrikzählprogramm
Wir verwenden Nirvana , eine universelle Computerplattform. Es beschreibt formal die Reihenfolge, in der Prozesse gestartet werden. Zusammen mit dem internen Scheduler (Scheduler) ersetzt uns Nirvana durch eine Reihe von Bash-Skripten und Cron.
Ein in Python geschriebenes Programm wird regelmäßig ausgeführt und fordert die zur Berechnung der Metriken erforderlichen Daten an.
Aufgabeneinstellungssystem
Daten zur Berechnung von Metriken in unserem Fall werden in Yandex.Tracker gespeichert. Als Schnittstelle zu den Daten verwenden wir die Yandex.Tracker Python-API - dies ist ein Wrapper der HTTP-API, mit dem Informationen in Datenstrukturen, die für die weitere Verarbeitung geeignet sind, schneller und einfacher empfangen werden können.
Sie können ein praktisches System mit einer geeigneten API auswählen, z. B. Jira.
Kartenvorbereitungssystem
Nach der Berechnung der Metriken basierend auf den Daten von Yandex.Tracker generiert unser Programm JSON-Dateien und überträgt sie an den internen Service von Yandex.Statistics, um Diagramme zu zeichnen.
Sie können eine Art JS-Bibliothek verwenden, mit der Diagramme erstellt werden können. Eine Übersicht über einige ähnliche Lösungen finden Sie auf Habré:
15 besten JavaScript-Bibliotheken
Im nächsten Teil werden wir beschreiben, wie wir die Qualitätsmetriken der Benutzerdokumentation berücksichtigen.