Moien, Habr! Mäin Numm ass Lesha, ech sinn e Systemanalytiker fir ee vun de Produktteams vun Alfa-Bank. Elo entwéckelen ech eng nei Online Bank fir juristesch Entitéiten an eenzel Entrepreneuren.
A wann Dir en Analyst sidd, besonnesch an esou engem Kanal, kënnt Dir néierens ouni Dokumentatioun an enk Aarbecht mat him kréien. An Dokumentatioun ass eppes wat ëmmer vill Froen opwerft. Firwat ass d'Webapplikatioun net beschriwwen? Firwat weist d'Spezifikatioun un wéi de Service funktionnéiert, awer et funktionnéiert guer net sou? Firwat ass et datt nëmmen zwee Leit, vun deenen een et geschriwwen huet, d'Spezifikatioun verstinn?
Wéi och ëmmer, Dokumentatioun kann aus offensichtleche Grënn net ignoréiert ginn. A fir eist Liewen méi einfach ze maachen, hu mir décidéiert d'Qualitéit vun der Dokumentatioun ze evaluéieren. Wéi mir dat genee gemaach hunn a wéi eng Conclusiounen mir komm sinn, steet ënnert dem Schnëtt.
Dokumentatioun Qualitéit
Fir net e puer Dose mol am Text "New Internet Bank" ze widderhuelen, schreiwen ech NIB. Elo hu mir méi wéi eng Dosen Teams déi un der Entwécklung vun NIB fir Entrepreneuren a juristesch Entitéite schaffen. Ausserdeem erstellt jidderee vun hinnen entweder seng eege Dokumentatioun fir en neie Service oder Webapplikatioun vun Null, oder mécht Ännerunge fir déi aktuell. Kann d'Dokumentatioun mat dëser Approche am Prinzip vun héich Qualitéit sinn?
A fir d'Qualitéit vun der Dokumentatioun ze bestëmmen, hu mir dräi Haaptcharakteristiken identifizéiert.
- Et muss komplett sinn. Dëst kléngt éischter Kapitän-ähnlech, awer et ass wichteg ze notéieren. Et soll am Detail all Elementer vun der ëmgesat Léisung beschreiwen.
- Et muss aktuell sinn. Dat ass, entspriechen der aktueller Ëmsetzung vun der Léisung selwer.
- Et soll verständlech sinn. Also datt d'Persoun déi et benotzt, genee versteet wéi d'Léisung ëmgesat gëtt.
Zesummefaassend - komplett, aktuell a verständlech Dokumentatioun.
Poll
Fir d'Qualitéit vun der Dokumentatioun ze bewäerten, hu mir décidéiert déi Leit ze interviewen déi direkt domat schaffen: NIB Analysten. D'Bewerber goufen opgefuerdert 10 Aussoen ze evaluéieren no dem Schema "Op enger Skala vun 1 bis 5 (ganz net averstan - ganz averstanen)."
D'Aussoe reflektéiert d'Charakteristiken vun der qualitativer Dokumentatioun an der Meenung vun den Ëmfro-Compilateuren iwwer NIB-Dokumenter.
- D'Dokumentatioun fir d'NIB Uwendungen ass aktuell a voll konsequent mat hirer Ëmsetzung.
- D'Ëmsetzung vun NIB Uwendungen ass voll dokumentéiert.
- Dokumentatioun fir NIB Uwendungen ass nëmme fir funktionell Ënnerstëtzung gebraucht.
- Dokumentatioun fir NIB Uwendungen ass aktuell am Moment vun hirer Soumissioun fir funktionell Ënnerstëtzung.
- NIB Applikatioun Entwéckler benotzen Dokumentatioun fir ze verstoen wat se musse implementéieren.
- Et gëtt genuch Dokumentatioun fir d'NIB Uwendungen fir ze verstoen wéi se ëmgesat ginn.
- Ech aktualiséieren direkt d'Dokumentatioun iwwer NIB Projeten wa se finaliséiert sinn (vu menger Equipe).
- NIB Applikatioun Entwéckler iwwerpréiwen Dokumentatioun.
- Ech hunn e kloert Verständnis wéi Dir Dokumentatioun fir NIB Projete virbereet.
- Ech verstinn wann ech schreiwen / Aktualiséierung vun Dokumentatioun fir NIB Projeten.
Et ass kloer datt einfach "Vun 1 bis 5" äntweren vläicht net déi néideg Detailer verroden, sou datt eng Persoun e Kommentar op all Artikel hannerloosst.
Mir hunn dat alles duerch Corporate Slack gemaach - mir hunn einfach eng Invitatioun un Systemanalyten geschéckt fir eng Ëmfro ze maachen. Et waren 15 Analysten (9 vu Moskau a 6 vu St. Petersburg). Nodeems d'Ëmfro ofgeschloss ass, hu mir en Duerchschnëttsscore fir jiddereng vun den 10 Aussoen generéiert, déi mir dann standardiséiert hunn.
Dëst ass wat geschitt ass.
D'Ëmfro huet gewisen datt obwuel Analysten geneigt sinn ze gleewen datt d'Ëmsetzung vun NIB Uwendungen voll dokumentéiert ass, si ginn net eendeiteg Accord (0.2). Als spezifescht Beispill hu se drop higewisen datt eng Zuel vun Datenbanken a Schlaangen aus existente Léisungen net vun der Dokumentatioun ofgedeckt sinn. Den Entwéckler ass fäeg dem Analyst ze soen datt net alles dokumentéiert ass. Awer d'Thes, datt d'Entwéckler d'Dokumentatioun iwwerpréiwen, krut och keng eendeiteg Ënnerstëtzung (0.33). Dat ass, de Risiko vun onkomplett Beschreiwung vun ëmgesat Léisungen bleift.
D'Relevanz ass méi einfach - obwuel et erëm kee kloeren Accord ass (0,13), sinn d'Analysten nach ëmmer geneigt d'Dokumentatioun als relevant ze betruechten. D'Kommentaren hunn eis erlaabt ze verstoen datt Problemer mat der Relevanz méi dacks un der Front sinn wéi an der Mëtt. Wéi och ëmmer, si hunn eis näischt iwwer de Backing geschriwwen.
Wéi fir ob d'Analysten selwer verstinn wann et néideg ass Dokumentatioun ze schreiwen an ze aktualiséieren, war den Accord vill méi eenheetlech (1,33), och säin Design (1.07). Wat hei als Nodeel bemierkt gouf, war de Mangel un eenheetleche Reegele fir d'Dokumentatioun z'erhalen. Dofir, fir net de Modus "Wien an de Bësch geet, wien kritt Brennholz" auszeschalten, musse se op Beispiller vun existéierende Dokumentatioun schaffen. Dofir ass en nëtzlechen Wonsch e Standard fir Dokumentmanagement ze kreéieren an Templates fir hir Deeler z'entwéckelen.
Dokumentatioun fir NIB Uwendungen ass aktuell am Moment vun der Soumissioun fir funktionell Ënnerstëtzung (0.73). Dëst ass verständlech, well ee vun de Critèrë fir e Projet fir funktionell Ënnerstëtzung ofzeginn ass déi aktuell Dokumentatioun. Et ass och genuch fir d'Ëmsetzung ze verstoen (0.67), obwuel heiansdo Froen bleiwen.
Mee wat d'Befroten net (ganz eestëmmeg) d'accord waren, war datt d'Dokumentatioun fir NIB Uwendungen am Prinzip just fir funktionell Ënnerstëtzung gebraucht gëtt (-1.53). Analysten goufen am meeschten als Konsumenten vun Dokumentatioun ernimmt. De Rescht vun der Equipe (Entwéckler) - vill manner oft. Ausserdeem gleewen d'Analysten datt d'Entwéckler keng Dokumentatioun benotzen fir ze verstoen wat se musse implementéieren, obwuel net eestëmmeg (-0.06). Dëst gëtt iwwregens och erwaart a Bedéngungen, wou d'Codeentwécklung an d'Dokumentatiounsschrëft parallel virugoen.
Wat ass den Haaptgrond a firwat brauche mir dës Zuelen?
Fir d'Qualitéit vun den Dokumenter ze verbesseren, hu mir decidéiert déi folgend ze maachen:
- Frot den Entwéckler fir schrëftlech Dokumenter ze iwwerpréiwen.
- Wa méiglech, Aktualiséierung vun Dokumentatioun op eng fristgerecht Manéier, virun éischt.
- Erstellt an adoptéiert e Standard fir NIB-Projeten ze dokumentéieren, sou datt jidderee séier kann verstoen wéi eng Systemelementer a wéi genau solle beschriwwe ginn. Gutt, entwéckelen passende Templates.
All dëst soll hëllefen d'Qualitéit vun den Dokumenter op en neien Niveau ze erhéijen.
Op d'mannst hoffen ech.
Source: will.com