ProHoster > Blogs > interneta ziņas > Kā mēs novērtējām dokumentācijas kvalitāti

Kā mēs novērtējām dokumentācijas kvalitāti

Sveiks, Habr! Mani sauc Lesha, es esmu sistēmu analÄ«tiÄ·is vienā no Alfa-Bank produktu komandām. Tagad izstrādāju jaunu tieÅ”saistes banku juridiskām personām un individuālajiem uzņēmējiem.

Un, kad esat analÄ«tiÄ·is, it Ä«paÅ”i Ŕādā kanālā, jÅ«s nekur nevarat nokļūt bez dokumentācijas un cieÅ”a darba ar to. Un dokumentācija vienmēr rada daudz jautājumu. Kāpēc tÄ«mekļa lietojumprogramma nav aprakstÄ«ta? Kāpēc specifikācijā ir norādÄ«ts, kā pakalpojumam jādarbojas, bet tas tā nemaz nedarbojas? Kāpēc tikai divi cilvēki, no kuriem viens to uzrakstÄ«ja, var saprast specifikāciju?

Kā mēs novērtējām dokumentācijas kvalitāti

Tomēr acÄ«mredzamu iemeslu dēļ dokumentāciju nevar ignorēt. Un, lai atvieglotu mÅ«su dzÄ«vi, mēs nolēmām novērtēt dokumentācijas kvalitāti. Tas, kā tieÅ”i mēs to izdarÄ«jām un pie kādiem secinājumiem nonācām, ir zem griezuma.

Dokumentācijas kvalitāte

Lai tekstā neatkārtotos ā€œJaunā internetbankaā€ vairākus desmitus reižu, uzrakstÄ«Å”u NIB. Tagad pie NIB izstrādes uzņēmējiem un juridiskām personām strādā vairāk nekā ducis komandu. Turklāt katrs no tiem vai nu izveido savu dokumentāciju jaunam pakalpojumam vai tÄ«mekļa lietojumprogrammai no nulles, vai arÄ« veic izmaiņas paÅ”reizējā. Vai ar Å”o pieeju dokumentācija principā var bÅ«t kvalitatÄ«va?

Un, lai noteiktu dokumentācijas kvalitāti, mēs esam identificējuÅ”i trÄ«s galvenās Ä«paŔības.

  1. Tam jābūt pilnīgam. Tas izklausās gluži kā kapteinis, taču ir svarīgi to atzīmēt. Tajā sīki jāapraksta visi ieviestā risinājuma elementi.
  2. Tam jābÅ«t aktuālam. Tas ir, atbilst paÅ”a risinājuma paÅ”reizējai ievieÅ”anai.
  3. Tam vajadzētu būt saprotamam. Lai persona, kas to izmanto, precīzi saprastu, kā risinājums tiek ieviests.

Rezumējot - pilnīga, aktuāla un saprotama dokumentācija.

ŠžŠæрŠ¾Ń

Lai novērtētu dokumentācijas kvalitāti, mēs nolēmām intervēt tos, kuri tieÅ”i ar to strādā: NIB analÄ«tiÄ·us. Respondentiem tika lÅ«gts novērtēt 10 apgalvojumus pēc shēmas ā€œSkalā no 1 lÄ«dz 5 (pilnÄ«gi nepiekrÄ«tu - pilnÄ«gi piekrÄ«tu).ā€

Izteikumi atspoguļoja kvalitatīvās dokumentācijas raksturojumu un aptaujas sastādītāju viedokli par NIB dokumentiem.

  1. NIB pieteikumu dokumentācija ir atjaunināta un pilnībā atbilst to ievieŔanai.
  2. NIB lietojumprogrammu ievieÅ”ana ir pilnÄ«bā dokumentēta.
  3. NIB lietojumprogrammu dokumentācija ir nepiecieŔama tikai funkcionālajam atbalstam.
  4. NIB pieteikumu dokumentācija ir aktuāla brīdī, kad tās tiek iesniegtas funkcionālajam atbalstam.
  5. NIB lietojumprogrammu izstrādātāji izmanto dokumentāciju, lai saprastu, kas viņiem ir jāievieÅ”.
  6. Ir pietiekami daudz dokumentācijas, lai NIB lietojumprogrammas saprastu, kā tās tiek ieviestas.
  7. Es nekavējoties atjauninu dokumentāciju par NIB projektiem, ja tie ir pabeigti (mana komanda).
  8. NIB lietojumprogrammu izstrādātāji izskata dokumentāciju.
  9. Man ir skaidra izpratne par to, kā sagatavot dokumentāciju NIB projektiem.
  10. Es saprotu, kad rakstīt/atjaunināt NIB projektu dokumentāciju.

Skaidrs, ka, vienkārÅ”i atbildot ā€œNo 1 lÄ«dz 5ā€, nepiecieÅ”amās detaļas var neatklāt, tāpēc cilvēks var atstāt komentāru par katru preci.

Mēs to visu izdarÄ«jām, izmantojot korporatÄ«vo Slack ā€” mēs vienkārÅ”i nosÅ«tÄ«jām sistēmas analÄ«tiÄ·iem uzaicinājumu veikt aptauju. Bija 15 analÄ«tiÄ·i (9 no Maskavas un 6 no Sanktpēterburgas). Pēc aptaujas pabeigÅ”anas mēs izveidojām vidējo punktu skaitu katram no 10 apgalvojumiem, kurus pēc tam standartizējām.

Tā tas notika.

Kā mēs novērtējām dokumentācijas kvalitāti

Aptauja parādÄ«ja, ka, lai gan analÄ«tiÄ·i sliecas uzskatÄ«t, ka NIB lietojumprogrammu ievieÅ”ana ir pilnÄ«bā dokumentēta, viņi nedod viennozÄ«mÄ«gu piekriÅ”anu (0.2). Kā konkrētu piemēru viņi norādÄ«ja, ka vairākas datu bāzes un rindas no esoÅ”ajiem risinājumiem nav iekļautas dokumentācijā. Izstrādātājs var pateikt analÄ«tiÄ·im, ka ne viss ir dokumentēts. Taču tēze, ka izstrādātāji izskata dokumentāciju, arÄ« neguva nepārprotamu atbalstu (0.33). Tas ir, pastāv risks, ka ieviesto risinājumu apraksts bÅ«s nepilnÄ«gs.

AtbilstÄ«ba ir vienkārŔāka - lai gan atkal nav skaidras vienoÅ”anās (0,13), analÄ«tiÄ·i joprojām sliecas uzskatÄ«t, ka dokumentācija ir bÅ«tiska. Komentāri ļāva mums saprast, ka problēmas ar atbilstÄ«bu biežāk ir priekŔā, nevis vidÅ«. Tomēr viņi mums neko nerakstÄ«ja par atbalstu.

Runājot par to, vai analÄ«tiÄ·i paÅ”i saprot, kad ir jāraksta un jāatjaunina dokumentācija, vienoÅ”anās bija daudz vienveidÄ«gāka (1,33), ieskaitot tās dizainu (1.07). Å eit kā neērtÄ«bas tika atzÄ«mēts vienotu dokumentācijas uzturÄ“Å”anas noteikumu trÅ«kums. Tāpēc, lai netiktu ieslēgts režīms ā€œKurÅ” iet mežā, kas dabÅ« malkuā€, jāstrādā, balstoties uz esoŔās dokumentācijas piemēriem. Tāpēc lietderÄ«ga vēlme ir izveidot dokumentu pārvaldÄ«bas standartu un izstrādāt veidnes to daļām.

NIB pieteikumu dokumentācija ir aktuāla funkcionālā atbalsta iesniegÅ”anas brÄ«dÄ« (0.73). Tas ir saprotams, jo viens no kritērijiem projekta iesniegÅ”anai funkcionālajam atbalstam ir aktuāla dokumentācija. Pietiek arÄ«, lai saprastu ievieÅ”anu (0.67), lai gan dažkārt paliek jautājumi.

Bet kam respondenti nepiekrita (diezgan vienbalsÄ«gi), ka dokumentācija NIB pieteikumiem principā ir nepiecieÅ”ama tikai funkcionālajam atbalstam (-1.53). Kā dokumentācijas patērētāji visbiežāk tika minēti analÄ«tiÄ·i. Pārējā komanda (izstrādātāji) - daudz retāk. Turklāt analÄ«tiÄ·i uzskata, ka izstrādātāji neizmanto dokumentāciju, lai saprastu, kas viņiem jāievieÅ”, lai gan ne vienbalsÄ«gi (-0.06). Tas, starp citu, sagaidāms arÄ« apstākļos, kad koda izstrāde un dokumentācijas rakstÄ«Å”ana norit paralēli.

Kāda ir bÅ«tÄ«ba un kāpēc mums ir vajadzÄ«gi Å”ie skaitļi?

Lai uzlabotu dokumentu kvalitāti, mēs nolēmām rÄ«koties Ŕādi:

  1. Lūdziet izstrādātājam pārskatīt rakstiskos dokumentus.
  2. Ja iespējams, savlaicÄ«gi atjauniniet dokumentāciju, vispirms pa priekÅ”u.
  3. Izveidojiet un pieņemiet NIB projektu dokumentÄ“Å”anas standartu, lai ikviens varētu ātri saprast, kuri sistēmas elementi un kā tieÅ”i ir jāapraksta. Nu, izstrādājiet atbilstoÅ”as ā€‹ā€‹veidnes.

Tam visam vajadzētu palīdzēt paaugstināt dokumentu kvalitāti jaunā līmenī.

Vismaz es tā ceru.

Avots: www.habr.com

Pievieno komentāru