Hallo, Habr! My naam is Lesha, ek is 'n stelselontleder vir een van Alfa-Bank se produkspanne. Nou ontwikkel ek 'n nuwe aanlynbank vir regspersone en individuele entrepreneurs.
En wanneer jy 'n ontleder is, veral in so 'n kanaal, kan jy nêrens kom sonder dokumentasie en noue werk daarmee nie. En dokumentasie is iets wat altyd baie vrae laat ontstaan. Waarom word die webtoepassing nie beskryf nie? Hoekom dui die spesifikasie aan hoe die diens moet werk, maar dit werk glad nie so nie? Hoekom is dit dat net twee mense, van wie een dit geskryf het, die spesifikasie kan verstaan?
Dokumentasie kan egter om ooglopende redes nie geïgnoreer word nie. En om ons lewe makliker te maak, het ons besluit om die kwaliteit van dokumentasie te evalueer. Hoe ons dit presies gedoen het en tot watter gevolgtrekkings ons gekom het, is onder die snit.
Dokumentasie kwaliteit
Om nie "Nuwe Internet Bank" 'n paar dosyn keer in die teks te herhaal nie, sal ek NIB skryf. Nou het ons meer as 'n dosyn spanne wat aan die ontwikkeling van NIB vir entrepreneurs en regspersone werk. Boonop skep elkeen van nuuts af sy eie dokumentasie vir 'n nuwe diens of webtoepassing, of maak veranderinge aan die huidige een. Met hierdie benadering, kan die dokumentasie in beginsel van hoë gehalte wees?
En om die kwaliteit van dokumentasie te bepaal, het ons drie hoofkenmerke geïdentifiseer.
- Dit moet volledig wees. Dit klink nogal kaptein-agtig, maar dit is belangrik om daarop te let. Dit moet alle elemente van die geïmplementeerde oplossing in detail beskryf.
- Dit moet relevant wees. Dit wil sê, stem ooreen met die huidige implementering van die oplossing self.
- Dit moet verstaanbaar wees. Sodat die persoon wat dit gebruik presies verstaan hoe die oplossing geïmplementeer word.
Om op te som - volledige, bygewerkte en verstaanbare dokumentasie.
Опрос
Om die kwaliteit van die dokumentasie te evalueer, het ons besluit om 'n onderhoud te voer met diegene wat direk daarmee werk: NIB-ontleders. Respondente is gevra om 10 stellings te evalueer volgens die skema "Op 'n skaal van 1 tot 5 (stem heeltemal nie saam - stem heeltemal saam)."
Die stellings het die kenmerke van kwalitatiewe dokumentasie en die mening van die opname-samestellers oor NIB-dokumente weerspieël.
- Die dokumentasie vir die NIB-toepassings is op datum en ten volle in ooreenstemming met die implementering daarvan.
- Die implementering van NIB-toepassings is volledig gedokumenteer.
- Dokumentasie vir NIB-toepassings word slegs benodig vir funksionele ondersteuning.
- Dokumentasie vir NIB-aansoeke is op datum ten tyde van hul indiening vir funksionele ondersteuning.
- NIB-toepassingsontwikkelaars gebruik dokumentasie om te verstaan wat hulle moet implementeer.
- Daar is genoeg dokumentasie vir die NIB-toepassings om te verstaan hoe hulle geïmplementeer word.
- Ek werk dokumentasie oor NIB-projekte stiptelik op as hulle gefinaliseer word (deur my span).
- NIB-toepassingsontwikkelaars hersien dokumentasie.
- Ek het 'n duidelike begrip van hoe om dokumentasie vir NIB-projekte voor te berei.
- Ek verstaan wanneer om dokumentasie vir NIB-projekte te skryf/by te werk.
Dit is duidelik dat die antwoord van "Van 1 tot 5" dalk nie die nodige besonderhede openbaar nie, so 'n persoon kan 'n opmerking oor elke item lewer.
Ons het dit alles deur korporatiewe Slack gedoen – ons het bloot 'n uitnodiging aan stelselontleders gestuur om 'n opname te neem. Daar was 15 ontleders (9 van Moskou en 6 van St. Petersburg). Nadat die opname voltooi is, het ons 'n gemiddelde telling vir elk van die 10 stellings gegenereer, wat ons dan gestandaardiseer het.
Dit is wat gebeur het.
Die opname het getoon dat alhoewel ontleders geneig is om te glo dat die implementering van NIB-toepassings volledig gedokumenteer is, gee hulle nie ondubbelsinnige ooreenstemming nie (0.2). As 'n spesifieke voorbeeld het hulle daarop gewys dat 'n aantal databasisse en rye van bestaande oplossings nie deur dokumentasie gedek is nie. Die ontwikkelaar kan vir die ontleder sê dat nie alles gedokumenteer is nie. Maar die tesis dat ontwikkelaars dokumentasie hersien, het ook nie onomwonde ondersteuning ontvang nie (0.33). Dit wil sê, die risiko van onvolledige beskrywing van geïmplementeerde oplossings bly.
Relevansie is makliker – hoewel daar weer geen duidelike ooreenkoms is nie (0,13), is ontleders steeds geneig om die dokumentasie as relevant te beskou. Die opmerkings het ons toegelaat om te verstaan dat probleme met relevansie meer dikwels aan die voorkant as in die middel is. Hulle het egter niks vir ons geskryf oor rugsteun nie.
Wat betref of die ontleders self verstaan wanneer dit nodig is om dokumentasie te skryf en by te werk, was die ooreenkoms baie meer eenvormig (1,33), insluitend die ontwerp (1.07). Wat hier as 'n ongerief opgemerk is, was die gebrek aan eenvormige reëls vir die instandhouding van dokumentasie. Daarom, om nie die "Wie gaan bos toe, wie kry vuurmaakhout"-modus aan te skakel nie, moet hulle op voorbeelde van bestaande dokumentasie werk. Daarom is 'n nuttige wens om 'n standaard vir dokumentbestuur te skep en sjablone vir hul dele te ontwikkel.
Dokumentasie vir NIB-aansoeke is tans op die tydstip van indiening vir funksionele ondersteuning (0.73). Dit is verstaanbaar, want een van die kriteria vir die indiening van 'n projek vir funksionele ondersteuning is bygewerkte dokumentasie. Dit is ook voldoende om die implementering te verstaan (0.67), hoewel daar soms vrae oorbly.
Maar waarmee die respondente nie (heelwat eenparig) saamgestem het nie, is dat dokumentasie vir NIB-aansoeke in beginsel net nodig is vir funksionele ondersteuning (-1.53). Ontleders is die meeste genoem as verbruikers van dokumentasie. Die res van die span (ontwikkelaars) - baie minder dikwels. Boonop glo ontleders dat ontwikkelaars nie dokumentasie gebruik om te verstaan wat hulle moet implementeer nie, hoewel nie eenparig nie (-0.06). Dit word terloops ook verwag in toestande waar kodeontwikkeling en dokumentasieskryf parallel voortgaan.
Wat is die slotsom en hoekom het ons hierdie getalle nodig?
Om die kwaliteit van dokumente te verbeter, het ons besluit om die volgende te doen:
- Vra die ontwikkelaar om geskrewe dokumente te hersien.
- Indien moontlik, werk dokumentasie betyds op, voor eers.
- Skep en aanvaar 'n standaard vir die dokumentasie van NIB-projekte sodat almal vinnig kan verstaan watter stelselelemente en hoe presies beskryf moet word. Wel, ontwikkel toepaslike sjablone.
Dit alles behoort te help om die kwaliteit van dokumente na 'n nuwe vlak te verhoog.
Ten minste hoop ek so.
Bron: will.com