Programmatūras dokumentēšana


Programmatūras dokumentēšana

Programmatūras izstrādes projekta rezultātu „trīs vaļi” ir:

  • dažādi izstrādes laikā tapuši dokumenti,
  • programmatūras kods (kas patiesībā ir pilnīgākā dokumentācija, kāda vien programmatūrai var būt),
  • pati darbināmā programmatūra (izpildkods).

Katrā izstrādes procesā kā tiešs vai netiešs rezultāts rodas dokuments vai vismaz pieraksts. Dokumentus var iedalīt divās grupās pēc to piederības:

  • iekšējie dokumenti, par kuriem pasūtītājs parasti zina, ka tādi mēdz būt, tomēr konkrētā projektā neiedziļinās to saturā un esamībā (ja pasūtītājs vēlas skatīt vai iegūt savā īpašumā šos dokumentus, tad par to jāvienojas ar izstrādātāju),
  • nododamie dokumenti, kuru izstrādes fakts ir fiksēts līgumā un kurš ir viens no taustāmajiem programmatūras izstrādes nodevumiem ar noteiktām kvalitātes prasībām.

Iedalot dokumentus pēc to satura, var iegūt, piemēram, šādas grupas:

  • procesu izpildi aprakstošā dokumentācija (piemēram, akcepttestēšanas procedūra vai konfigurācijas pārvaldības vadlīnijas),
  • starprezultātu dokumentācija kādā procesā (piemēram, programmatūras pirmsnodošanas testēšanas pārskats),
  • gala produktu aprakstošā dokumentācija (piemēram, programmatūras projektējuma apraksts),
  • gala produkta sastāvdaļa (lietotāja dokumentācija).

 Programmatūras izstrādes laikā radītajiem dokumentiem visbiežāk tiek lietotas šādas galvenās prasības to kvalitātei:

  1. atbilstība standartam,
  2. atbilstība dokumenta izstrādes laikā abpusēji saskaņotām un rakstiski noformulētām pasūtītāja vēlmēm un norunām.

Kā papildus nodrošinājums var būt prasība izstrādātājam procesa organizēšanā nodrošināt atbilstību kādam procesu reglamentējošajam standartam (šādā gadījumā noteikti jāvienojas par veidu, kā tieši izstrādātājs lai pierāda šo atbilstību). Piemēram, lietotāja dokumentācijas gala rezultātam – dokumentam iespējams prasīt atbilstību standartam 1063:2001 IEEE Standard for Software User Documentation, bet pašam lietotāja dokumentācijas izstrādes procesam – atbilstību standartam 15910:1999 Information Technology – Software user documentation process. Šajā standartā cita starpā ir aprakstīta darbietilpības aprēķināšana dokumentācijas izstrādei, kuru, kombinējot ar praksē uzkrātajām zināšanām un statistiku konkrētā organizācijā, var izmantot arī citu dokumentu izstrādes darbietilpības prognozēšanai.

Īsumā par dokumentēšanu

Iespējams, ka ir dzirdēti jēdziens – programmatūras dzīves cikls, kas – vienkāršojot -raksturo, kādā attīstības stadijā atrodas programmatūra (izstrādē, testēšanā, ekspluatācijā) u.c. Līdzīgi dzīves cikla jēdzienu pielieto arī citur, runājot par, piemēram, problēmziņojuma dzīves ciklu vai dokumenta dzīves ciklu. Patiesībā tas ir diezgan vienkārši – jāvienojas par dokumenta iespējamajiem statusiem, piemēram, „melnraksts”, „tīrraksts”, „spēkā esošs”, „arhivēts”, un dokumentam vienmēr jābūt atbilstoši piešķirtam kādam no šiem statusiem.

Grūtākais parasti ir izveidot šo statusu sarakstu. Salīdzinoši vieglāk ir vienoties par kārtību, kādā šie statusi tiks piešķirti, un vienoties par veidu, kā tiks uzturēta informācija par dokumentiem un to statusiem. Praksē to var organizēt gan ar dārgiem konfigurācijas pārvaldības rīkiem, gan ar organizatoriskām norunām un pieejas tiesību pārvaldību, izmantojot vispārpieejamus un vienkāršus rīkus. Manā darba pieredzē ir veiksmīgi piemēri arī ar dokumentu glabāšanu direktorijās ar norunātu lietošanu kārtību.

Par svarīgāko līdzekli dokumenta kvalitātes nodrošināšanai var uzskatīt dokumenta apskates, kuru laikā parasti izmanto kontroljautājumu sarakstus un dokumentam izvirzīto prasību sarakstu (ja tas nav iekļauts kontroljautājumu sarakstā). Piemēram, programmatūras prasību specifikācijas apskates laikā apskates dalībnieki pārbauda apskatāmā dokumenta atbilstību prasību specifikācijas kontroljautājumu sarakstam, piemēram, “vai specifikācijā visām prasībām ir norādīti ieejas dati? Jā/nē/nav aktuāli” u.tml. Balstoties uz iegūtajiem rezultātiem, apskates dalībnieki pieņem slēdzienu, vai dokuments ir gatavs nodošanai, vai ir atdodams izstrādātājam pilnveidošanai.

Nododot jaunu dokumenta versiju, svarīgi lasītājam nodrošināt iespēju saprast, kas saturā ir mainījies salīdzinājumā ar iepriekšējo versiju. To var nodrošināt vairākos veidos, piemēram, pievienot lapu ar izmaiņu aprakstu attiecībā pret iepriekšējo versiju, skatīt izmaiņas ar izstrādes vides līdzekļiem, piemēram, Track changes vai Compare u.c. – svarīgi savā starpā vienoties par šo veidu. Mūsdienīgas dokumentu izstrādes vides piedāvā izvēles iespēju no vienkāršas rakstāmmašīnas līmeņa programmatūras līdz jaudīgai publicēšanas sistēmai, no kuras ar pāris peles klikšķiem iespējams iegūt PDF, DHTML u.c. formātu dokumentus atkarībā no projekta vajadzībām. Protams, ir konkrēti apsvērumi vienas vai otras vides (Microsoft Word, Adobe FrameMaker u.c.) izvēlei, kuri ir jāskata kontekstā ar pasūtītāja un izstrādātāja vajadzībām un iespējām. Viens ieteikums gan ir pavisam drošs – dokumenta satura pirmavots jāuztur vienā un tikai vienā vidē. Es reiz pārliecināju projekta vadītāju nosūtīt dokumentētājus uz FrameMaker apmācībām, un process būtiski uzlabojās, jo pirms tam dokumentētāji sūtīja Word dokumentus vienīgajam FrameMaker zinātājam, lai viņš pārveido uz to.

Kopumā pieredze programmatūras izstrādē ļauj secināt, ka dokumentu sagatavošana un to kvalitātes novērtēšana joprojām ir aktuāla problēma visās nozarēs, kuras saskaras ar programmatūras iegādi. Kvalitātes prasības bieži vien var interpretēt dažādi un gala rezultāts ir atkarīgs gan no izstrādātāju un novērtētāju profesionalitātes, gan pareizi organizētas savstarpējās sadarbības.

P.S. Raksts tapis 2005.gadā, bet vērtēju, ka joprojām aktuāls

Advertisements

One response to this post.

  1. Posted by nuff on 23/03/2011 at 19:29

    Mūsdienās, real men neraksta garās dokumentācijas *.doc failos, bet gan raksta tīru kodu un pāris rindiņu īsus komentāru, no kuriem 1/4 ir references uz vareno Klingonu impēriju.
    Tāpat real men, māk lasīt citu sarkstītu kodu tik pat ātri, kā sauso un pareizi noformētu dokumentāciju.
    Kods ir vienīgā dokumentācija kura vienmēr būs updeitota un sasinhronizēta ar pēdējo produkta versiju!

    P.S Pārējie ir code mankiji un alga tādiem jāmaksā banānos!

    Like

    Atbildēt

Mans viedoklis:

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Mainīt )

Twitter picture

You are commenting using your Twitter account. Log Out / Mainīt )

Facebook photo

You are commenting using your Facebook account. Log Out / Mainīt )

Google+ photo

You are commenting using your Google+ account. Log Out / Mainīt )

Connecting to %s

%d bloggers like this: