Hallo, Habr! Mijn naam is Lesha, ik ben systeemanalist voor een van de productteams van Alfa-Bank. Nu ontwikkel ik een nieuwe online bank voor rechtspersonen en individuele ondernemers.
En als je analist bent, zeker in zo’n kanaal, kom je nergens zonder documentatie en kun je er nauw mee samenwerken. En documentatie is iets dat altijd veel vragen oproept. Waarom wordt de webapplicatie niet beschreven? Waarom wordt in de specificatie aangegeven hoe de dienst zou moeten werken, maar werkt het helemaal niet zo? Hoe komt het dat slechts twee mensen, van wie er één het heeft geschreven, de specificatie kunnen begrijpen?
Documentatie kan echter om voor de hand liggende redenen niet worden genegeerd. En om ons leven gemakkelijker te maken, hebben we besloten de kwaliteit van de documentatie te evalueren. Hoe we dit precies hebben gedaan en tot welke conclusies we zijn gekomen, staat hieronder.
Documentatie kwaliteit
Om “Nieuwe Internetbank” niet tientallen keren in de tekst te herhalen, zal ik NIB schrijven. Nu werken ruim een dozijn teams aan de ontwikkeling van NIB voor ondernemers en rechtspersonen. Bovendien creëert elk van hen zijn eigen documentatie voor een nieuwe dienst of webapplicatie, of brengt hij wijzigingen aan in de huidige. Kan de documentatie met deze aanpak in principe van hoge kwaliteit zijn?
En om de kwaliteit van documentatie te bepalen, hebben we drie hoofdkenmerken geïdentificeerd.
- Het moet compleet zijn. Dit klinkt nogal kapitein-achtig, maar het is belangrijk om op te merken. Het moet alle elementen van de geïmplementeerde oplossing in detail beschrijven.
- Het moet relevant zijn. Dat wil zeggen, overeenkomen met de huidige implementatie van de oplossing zelf.
- Het moet begrijpelijk zijn. Zodat degene die het gebruikt precies begrijpt hoe de oplossing wordt geïmplementeerd.
Samenvattend: volledige, actuele en begrijpelijke documentatie.
Interview
Om de kwaliteit van de documentatie te beoordelen, hebben we besloten mensen te interviewen die er direct mee werken: NIB-analisten. Respondenten werd gevraagd om 10 stellingen te beoordelen volgens het schema ‘Op een schaal van 1 tot 5 (helemaal mee oneens – helemaal mee eens)’.
De uitspraken weerspiegelden de kenmerken van kwalitatieve documentatie en de mening van de samenstellers van de enquête over NIB-documenten.
- De documentatie voor de NIB-applicaties is actueel en volledig consistent met de implementatie ervan.
- De implementatie van NIB-applicaties is volledig gedocumenteerd.
- Documentatie voor NIB-applicaties is alleen nodig voor functionele ondersteuning.
- Documentatie voor NIB-aanvragen is actueel op het moment dat deze worden ingediend voor functionele ondersteuning.
- NIB-applicatieontwikkelaars gebruiken documentatie om te begrijpen wat ze moeten implementeren.
- Er is voldoende documentatie voor de NIB-applicaties om te begrijpen hoe ze worden geïmplementeerd.
- Ik werk de documentatie over NIB-projecten onmiddellijk bij als deze zijn afgerond (door mijn team).
- NIB-applicatieontwikkelaars beoordelen de documentatie.
- Ik heb een duidelijk inzicht in het voorbereiden van documentatie voor NIB-projecten.
- Ik begrijp wanneer ik documentatie voor NIB-projecten moet schrijven/bijwerken.
Het is duidelijk dat het simpelweg beantwoorden van “Van 1 tot 5” misschien niet de nodige details onthult, dus iemand zou een opmerking over elk item kunnen achterlaten.
We deden dit allemaal via Slack van het bedrijf - we stuurden eenvoudigweg een uitnodiging naar systeemanalisten om een enquête in te vullen. Er waren 15 analisten (9 uit Moskou en 6 uit Sint-Petersburg). Na afloop van het onderzoek hebben we voor elk van de 10 stellingen een gemiddelde score gegenereerd, die we vervolgens hebben gestandaardiseerd.
Dit is wat er is gebeurd.
Uit het onderzoek bleek dat hoewel analisten geneigd zijn te geloven dat de implementatie van NIB-applicaties volledig gedocumenteerd is, zij geen eenduidige overeenstemming bereiken (0.2). Als concreet voorbeeld wezen zij erop dat een aantal databases en wachtrijen van bestaande oplossingen niet onder documentatie vielen. De ontwikkelaar kan de analist vertellen dat niet alles gedocumenteerd is. Maar ook de stelling dat ontwikkelaars documentatie beoordelen kreeg geen eenduidige steun (0.33). Dat wil zeggen dat het risico van onvolledige beschrijving van geïmplementeerde oplossingen blijft bestaan.
Relevantie is makkelijker – ook al is er wederom geen duidelijke overeenstemming (0,13), toch zijn analisten nog steeds geneigd de documentatie als relevant te beschouwen. Dankzij de opmerkingen konden we begrijpen dat problemen met relevantie vaker aan de voorkant zitten dan in het midden. Ze hebben ons echter niets geschreven over steun.
Wat betreft de vraag of de analisten zelf begrijpen wanneer het nodig is om documentatie te schrijven en bij te werken, was de overeenkomst veel uniformer (1,33), inclusief de opzet ervan (1.07). Wat hier als ongemak werd opgemerkt, was het ontbreken van uniforme regels voor het bijhouden van documentatie. Om de modus 'Wie gaat naar het bos, wie krijgt brandhout' niet in te schakelen, moeten ze daarom werken op basis van voorbeelden van bestaande documentatie. Het is daarom een nuttige wens om een standaard voor documentbeheer te creëren en sjablonen voor de onderdelen ervan te ontwikkelen.
Documentatie voor NIB-aanvragen is actueel op het moment van indiening voor functionele ondersteuning (0.73). Dit is begrijpelijk, want een van de criteria voor het indienen van een project voor functionele ondersteuning is actuele documentatie. Het is ook voldoende om de implementatie te begrijpen (0.67), hoewel er soms vragen blijven bestaan.
Maar waar de respondenten het niet (vrij unaniem) mee eens waren, was dat documentatie voor NIB-applicaties in principe alleen nodig is voor functionele ondersteuning (-1.53). Analisten werden het vaakst genoemd als consumenten van documentatie. De rest van het team (ontwikkelaars) - veel minder vaak. Bovendien zijn analisten van mening dat ontwikkelaars geen documentatie gebruiken om te begrijpen wat ze moeten implementeren, hoewel niet unaniem (-0.06). Dit wordt overigens ook verwacht in omstandigheden waarin de ontwikkeling van code en het schrijven van documentatie parallel verlopen.
Wat is de bottom line en waarom hebben we deze cijfers nodig?
Om de kwaliteit van de documenten te verbeteren, hebben we besloten het volgende te doen:
- Vraag de ontwikkelaar om schriftelijke documenten te beoordelen.
- Werk indien mogelijk de documentatie tijdig bij, eerst aan de voorzijde.
- Creëer en adopteer een standaard voor het documenteren van NIB-projecten, zodat iedereen snel kan begrijpen welke systeemelementen en hoe precies beschreven moeten worden. Ontwikkel geschikte sjablonen.
Dit alles zou moeten helpen de kwaliteit van documenten naar een nieuw niveau te tillen.
Dat hoop ik althans.
Bron: www.habr.com