Wie wir die Qualität der Dokumentation beurteilt haben

Hallo, Habr! Mein Name ist Lesha, ich bin Systemanalytikerin für eines der Produktteams der Alfa-Bank. Jetzt entwickle ich eine neue Online-Bank für juristische Personen und Einzelunternehmer.

Und wenn Sie ein Analyst sind, insbesondere in einem solchen Kanal, kommen Sie ohne Dokumentation und enge Arbeit damit nicht weiter. Und Dokumentation wirft immer viele Fragen auf. Warum wird die Webanwendung nicht beschrieben? Warum gibt die Spezifikation an, wie der Dienst funktionieren soll, funktioniert aber überhaupt nicht so? Warum können nur zwei Personen, von denen einer sie geschrieben hat, die Spezifikation verstehen?

Aus offensichtlichen Gründen kann die Dokumentation jedoch nicht ignoriert werden. Und um uns das Leben zu erleichtern, haben wir beschlossen, die Qualität der Dokumentation zu bewerten. Wie wir das genau gemacht haben und zu welchen Schlussfolgerungen wir gekommen sind, erfahren Sie weiter unten.

Dokumentationsqualität

Um „Neue Internetbank“ im Text nicht mehrere Dutzend Mal zu wiederholen, schreibe ich NIB. Mittlerweile beschäftigen wir mehr als ein Dutzend Teams, die an der Entwicklung von NIB für Unternehmer und juristische Personen arbeiten. Darüber hinaus erstellt jeder von ihnen entweder seine eigene Dokumentation für einen neuen Dienst oder eine neue Webanwendung von Grund auf oder nimmt Änderungen an der aktuellen vor. Kann die Dokumentation bei dieser Vorgehensweise grundsätzlich hochwertig sein?

Und um die Qualität der Dokumentation zu bestimmen, haben wir drei Hauptmerkmale identifiziert.

1. Es muss vollständig sein. Das klingt eher nach Kapitän, ist aber wichtig zu beachten. Es sollte alle Elemente der implementierten Lösung detailliert beschreiben.
2. Es muss aktuell sein. Das heißt, sie entsprechen der aktuellen Implementierung der Lösung selbst.
3. Es sollte verständlich sein. Damit der Anwender genau versteht, wie die Lösung umgesetzt wird.

Zusammenfassend: vollständige, aktuelle und verständliche Dokumentation.

Опрос

Um die Qualität der Dokumentation zu beurteilen, haben wir uns entschieden, diejenigen zu befragen, die direkt damit arbeiten: NIB-Analysten. Die Befragten wurden gebeten, 10 Aussagen nach dem Schema „Auf einer Skala von 1 bis 5 (stimme überhaupt nicht zu – stimme völlig zu)“ zu bewerten.

Die Aussagen spiegelten die Merkmale qualitativer Dokumentation und die Meinung der Umfrageersteller zu NIB-Dokumenten wider.

1. Die Dokumentation für die NIB-Anwendungen ist aktuell und stimmt vollständig mit ihrer Implementierung überein.
2. Die Implementierung von NIB-Anwendungen ist vollständig dokumentiert.
3. Die Dokumentation für NIB-Anwendungen wird nur zur funktionalen Unterstützung benötigt.
4. Die Dokumentation für NIB-Anwendungen ist zum Zeitpunkt ihrer Einreichung zur funktionalen Unterstützung aktuell.
5. Entwickler von NIB-Anwendungen nutzen die Dokumentation, um zu verstehen, was sie implementieren müssen.
6. Es gibt genügend Dokumentation für die NIB-Anwendungen, um zu verstehen, wie sie implementiert werden.
7. Ich aktualisiere die Dokumentation zu NIB-Projekten umgehend, wenn sie (von meinem Team) abgeschlossen sind.
8. NIB-Anwendungsentwickler überprüfen die Dokumentation.
9. Ich habe ein klares Verständnis dafür, wie man Dokumentation für NIB-Projekte erstellt.
10. Ich verstehe, wann Dokumentation für NIB-Projekte geschrieben/aktualisiert werden muss.

Es ist klar, dass die einfache Antwort „Von 1 bis 5“ möglicherweise nicht die notwendigen Details preisgibt, sodass eine Person zu jedem Punkt einen Kommentar hinterlassen könnte.

Wir haben das alles über Corporate Slack gemacht – wir haben einfach eine Einladung an Systemanalysten verschickt, an einer Umfrage teilzunehmen. Es waren 15 Analysten anwesend (9 aus Moskau und 6 aus St. Petersburg). Nach Abschluss der Umfrage haben wir für jede der 10 Aussagen einen Durchschnittswert generiert, den wir dann standardisiert haben.

Es stellte sich heraus, dass das was ist.

Die Umfrage ergab, dass Analysten zwar eher davon ausgehen, dass die Implementierung von NIB-Anwendungen vollständig dokumentiert ist, sie jedoch keine eindeutige Zustimmung geben (0.2). Als konkretes Beispiel wiesen sie darauf hin, dass eine Reihe von Datenbanken und Warteschlangen bestehender Lösungen nicht durch die Dokumentation abgedeckt seien. Der Entwickler kann dem Analysten mitteilen, dass nicht alles dokumentiert ist. Aber auch die These, dass Entwickler die Dokumentation überprüfen, fand keine eindeutige Unterstützung (0.33). Das heißt, das Risiko einer unvollständigen Beschreibung implementierter Lösungen bleibt bestehen.

Die Relevanz ist einfacher – obwohl es erneut keine eindeutige Übereinstimmung gibt (0,13), neigen Analysten immer noch dazu, die Dokumentation als relevant zu betrachten. Die Kommentare ließen uns verstehen, dass Probleme mit Relevanz häufiger im Vordergrund als in der Mitte liegen. Sie haben uns jedoch nichts über die Unterstützung geschrieben.

Was die Frage betrifft, ob die Analysten selbst verstehen, wann es notwendig ist, Dokumentation zu schreiben und zu aktualisieren, war die Vereinbarung viel einheitlicher (1,33), einschließlich ihres Designs (1.07). Als störend wurde hier das Fehlen einheitlicher Regeln zur Führung der Dokumentation festgestellt. Um den Modus „Wer geht in den Wald, wer holt Brennholz“ nicht einzuschalten, müssen sie daher anhand von Beispielen bestehender Dokumentation arbeiten. Daher besteht ein sinnvoller Wunsch darin, einen Standard für die Dokumentenverwaltung zu schaffen und Vorlagen für deren Teile zu entwickeln.

Die Dokumentation für NIB-Anträge ist zum Zeitpunkt der Einreichung für funktionale Unterstützung aktuell (0.73). Dies ist verständlich, denn eines der Kriterien für die Einreichung eines Projekts zur funktionalen Unterstützung ist eine aktuelle Dokumentation. Es reicht auch aus, die Implementierung zu verstehen (0.67), obwohl manchmal Fragen offen bleiben.

Was die Befragten jedoch (ganz einhellig) nicht stimmten, war, dass die Dokumentation für NIB-Anwendungen grundsätzlich nur zur funktionalen Unterstützung erforderlich ist (-1.53). Analysten wurden am häufigsten als Konsumenten von Dokumentationen genannt. Der Rest des Teams (Entwickler) – viel seltener. Darüber hinaus glauben Analysten, dass Entwickler keine Dokumentation verwenden, um zu verstehen, was sie implementieren müssen, wenn auch nicht einhellig (-0.06). Dies wird übrigens auch unter Bedingungen erwartet, bei denen Codeentwicklung und Dokumentationserstellung parallel erfolgen.

Was ist das Endergebnis und warum brauchen wir diese Zahlen?

Um die Qualität der Dokumente zu verbessern, haben wir uns für Folgendes entschieden:

1. Bitten Sie den Entwickler, schriftliche Dokumente zu überprüfen.
2. Wenn möglich, aktualisieren Sie die Dokumentation zeitnah, mit der Vorderseite zuerst.
3. Erstellen und übernehmen Sie einen Standard zur Dokumentation von NIB-Projekten, damit jeder schnell versteht, welche Systemelemente wie genau beschrieben werden sollen. Nun, entwickeln Sie entsprechende Vorlagen.

All dies soll dazu beitragen, die Qualität der Dokumente auf ein neues Niveau zu heben.

Zumindest hoffe ich das.

Source: habr.com