Hallo Habr! Mein Name ist Lesha, ich bin Systemanalyst bei einem der Produktteams der Alfa-Bank. Jetzt entwickle ich eine neue Internetbank für juristische Personen und Einzelunternehmer.
Und wenn Sie ein Analyst sind, insbesondere in einem solchen Kanal, ohne Dokumentation und harte Arbeit damit - nirgendwo. Und die Dokumentation wirft immer wieder viele Fragen auf. Warum wird die Webanwendung nicht beschrieben? Warum gibt die Spezifikation an, wie der Dienst funktionieren soll, aber er funktioniert überhaupt nicht? Warum können nur zwei Personen die Spezifikation verstehen, von denen einer sie geschrieben hat?
Die Dokumentation kann jedoch aus offensichtlichen Gründen nicht ignoriert werden. Um unser Leben zu vereinfachen, haben wir uns entschlossen, die Qualität der Dokumentation zu bewerten. Wie genau wir das gemacht haben und zu welchen Schlussfolgerungen wir gekommen sind - unter dem Schnitt.
Dokumentationsqualität
Um den Text „New Internet Bank“ nicht einige Dutzend Mal zu wiederholen, werde ich die NIB schreiben. Jetzt arbeiten über ein Dutzend Teams an der Entwicklung der NIB für Unternehmer und juristische Personen. Darüber hinaus erstellt jeder von ihnen entweder von Grund auf eine eigene Dokumentation für einen neuen Dienst oder eine neue Webanwendung oder nimmt Änderungen an der aktuellen vor. Kann bei diesem Ansatz die Dokumentation grundsätzlich von hoher Qualität sein?
Um die Qualität der Dokumentation zu bestimmen, haben wir drei Hauptmerkmale identifiziert.
- Es muss vollständig sein. Es klingt ziemlich kapitän, aber es ist wichtig zu beachten. Es sollte alle Elemente der implementierten Lösung detailliert beschreiben.
- Es sollte relevant sein. Das heißt, entsprechen der aktuellen Implementierung der Lösung selbst.
- Es sollte klar sein. Damit die Person, die es verwendet, versteht, wie die Lösung implementiert wird.
Zusammenfassen - vollständige, relevante und verständliche Dokumentation.
Umfrage
Um die Qualität der Dokumentation zu beurteilen, haben wir uns entschlossen, diejenigen zu befragen, die direkt damit arbeiten: NIB-Analysten. Die Befragten wurden gebeten, 10 Aussagen gemäß dem Schema „Auf einer Skala von 1 bis 5 (stimme überhaupt nicht zu - stimme voll und ganz zu)“ zu bewerten.
Die Vorwürfe spiegelten die Merkmale der Qualitätsdokumentation und die Meinung der Ersteller der Umfrage zu NIB-Dokumenten wider.
- Die Dokumentation zu NIB-Anwendungen ist relevant und entspricht voll und ganz ihrer Implementierung.
- Die Implementierung der NIB-Anwendungen ist vollständig dokumentiert.
- Die Dokumentation zu NIB-Anwendungen wird nur für die Funktionsunterstützung benötigt.
- Die Dokumentation zu NIB-Anträgen ist zum Zeitpunkt ihrer Einreichung für die funktionale Unterstützung relevant.
- Entwickler von NIB-Anwendungen verwenden die Dokumentation, um zu verstehen, was sie implementieren müssen.
- Die Dokumentation für die NIB-Anwendungen reicht aus, um zu verstehen, wie sie implementiert werden.
- Ich werde die Dokumentation zu NIB-Projekten rechtzeitig aktualisieren, wenn sie (von meinem Team) abgeschlossen sind.
- Entwickler von NIB-Anwendungen überprüfen die Dokumentation.
- Ich habe ein klares Verständnis dafür, wie man NIB-Projekte dokumentiert.
- Ich verstehe, wann Dokumentation zu NIB-Projekten geschrieben / aktualisiert werden muss.
Es ist klar, dass die Antwort „Von 1 bis 5“ nicht die erforderlichen Details enthüllen kann, sodass eine Person zu jedem Punkt einen Kommentar hinterlassen kann.
Wir haben dies alles über das Unternehmen Slack getan - wir haben einfach einen Vorschlag an die Systemanalysten gesendet, um an der Umfrage teilzunehmen. Es gab 15 Analysten (9 aus Moskau und 6 aus St. Petersburg). Nach Abschluss der Umfrage haben wir für jede der 10 Aussagen eine Durchschnittsbewertung gebildet, die dann normalisiert wurde.
Das ist passiert.
Die Umfrage ergab, dass Analysten zwar der Ansicht sind, dass die Implementierung von NIB-Anwendungen vollständig dokumentiert ist, jedoch keine eindeutige Übereinstimmung erzielen (0,2). Als konkretes Beispiel gaben sie an, dass eine Reihe von Datenbanken und Warteschlangen aus vorhandenen Lösungen nicht dokumentiert wurden. Der Entwickler kann dem Analysten mitteilen, dass nicht alles dokumentiert ist. Die These, dass Entwickler eine Überprüfung der Dokumentation durchführen, erhielt jedoch auch keine eindeutige Unterstützung (0,33). Das heißt, das Risiko unvollständiger Beschreibungen implementierter Lösungen bleibt bestehen.
Mit Relevanz ist es einfacher - obwohl es wieder keine eindeutige Übereinstimmung gibt (0,13), neigen Analysten immer noch dazu, die Dokumentation als relevant zu betrachten. Durch Kommentare konnten wir verstehen, dass es häufiger Probleme mit der Relevanz vorne als in der Mitte gibt. Es stimmt, sie haben nichts über Backing geschrieben.
In Bezug darauf, ob die Analysten selbst verstehen, wann die Dokumentation zu schreiben und zu aktualisieren ist, war die Vereinbarung bereits viel einheitlicher (1,33), einschließlich ihres Designs (1,07). Als Unannehmlichkeit wurde hier das Fehlen einheitlicher Regeln für die Aufrechterhaltung der Dokumentation festgestellt. Um das Regime „Wer ist im Wald, wer ist für Brennholz?“ Nicht einzubeziehen, müssen sie daher anhand von Beispielen bestehender Dokumentation arbeiten. Daher ein nützlicher Wunsch - einen Standard für die Pflege von Dokumenten zu erstellen, Vorlagen für ihre Teile zu entwickeln.
Die Dokumentation zu NIB-Anwendungen ist zum Zeitpunkt der Lieferung für die Funktionsunterstützung relevant (0,73). Dies ist verständlich, da eines der Kriterien für die Übergabe eines Projekts an den Funktionssupport die aktuelle Dokumentation ist. Es reicht auch aus, die Implementierung zu verstehen (0,67), obwohl manchmal Fragen offen bleiben.
Den Befragten stimmte jedoch nicht (eher einstimmig) zu, dass die Dokumentation zu NIB-Anwendungen im Prinzip nur für die funktionale Unterstützung erforderlich ist (-1,53). Am häufigsten wurden Analysten als Konsumenten von Dokumentation genannt. Die restlichen Teammitglieder (Entwickler) - viel seltener. Darüber hinaus glauben Analysten, dass Entwickler keine Dokumentation verwenden, um zu verstehen, was sie implementieren müssen, wenn auch nicht einstimmig (-0.06). Dies wird übrigens auch unter Bedingungen erwartet, bei denen die Codeentwicklung und das Schreiben von Dokumentation parallel verlaufen.
Was ist das Ergebnis und warum brauchen wir diese Zahlen
Um die Qualität der Dokumente zu verbessern, haben wir uns dazu entschlossen:
- Bitten Sie den Entwickler, schriftliche Dokumente zu überprüfen.
- Wenn möglich, aktualisieren Sie rechtzeitig die Dokumentation, die Vorderseite - an erster Stelle.
- Erstellen und übernehmen Sie einen Standard für die Dokumentation von NIB-Projekten, damit jeder schnell verstehen kann, welche Elemente des Systems und wie es zu beschreiben ist. Nun, entwickeln Sie geeignete Vorlagen.
All dies sollte dazu beitragen, die Qualität von Dokumenten auf ein neues Niveau zu heben.
Zumindest hoffe ich es.