User login

Languages

Dokumentēšana

Dažreiz šķiet, ka dokumentēšana ir viena no garlaicīgākajām padarīšanām, ar ko man ir nācies sastapties. Varbūt Dievs ir uzlicis analītiķim par pienākumu rakstīt specifikācijas, lai ielietu kādu darvas karoti viņa citkārt tik radošajā un aizraujošajā dzīvē.

Garlaicība, rakstot dokumentus, norāda, ka kaut kas tiek darīts nepareizi. Varbūt - dokumentam ir nepareizs uzstādījums.

Manuprāt, rakstot dokumentu, pats galvenais ir auditorija un mērķis, ar kādu šie cilvēki dokumentu izmantos. Ja to patur prātā, tad viss ir labi. Godīgi sakot, man nav laimējies redzēt dokumentus, kas vienlīdz labi kalpotu dažādiem mērķiem (žēl, jo vienmēr jau gribas ar vienu šāvienu nošaut vairākus zaķus).

Mēģinot apkopot to dokumentāciju, ko man nācies rakstīt, dokumentus var iedalīt divās grupās:

  • dokumenti, kas izsaka ideju
  • uzziņu literatūra

Idejas dokumentus noteikti nedrīkst ierobežot ar kādiem šabloniem vai standartiem. To mērķis ir visprecīzāk paust kādus noteiktus principus, un mērķis attaisno līdzekļus. Piemēram, sen sen, kad es vēl biju programmētājs, man bija kāds klients, kurš pārmeta, ka es neesmu laicīgi, kopā ar programmatūras versiju, piegādājis dokumentāciju. Tā bija taisnība, es tiešām biju nonācis lielā laika trūkumā. Mēs sākām runāt par to, kā un kad atrisināt šo problēmu, un man nejauši pa rokai trāpījās lapa ar shēmu, kurā bija attēloti programmas darbības principi. Viņš ieraudzīja to, un paziņoja, ka dokumentācija viņam nav steidzama, lai tikai es iedodu šo shēmu. Lūk - tā es saprotu veiksmīgu idejas dokumentu. Tam ir jābūt trāpīgam, nevis lielam.

Savukārt, uzziņu literatūras gadījumā mēs nevaram izvairīties no apjoma. Un rodas cita problēma - kā nodrošināt pienācīgu kvalitāti? Kā nodrošināt iespēju atrast dažādas iekšējas saistības - piemēram, kā dokuments palīdzēs nākotnes analītiķim, kas aprakstīs izmaiņas funkcionalitātē, identificēt saistītās funkcijas? Tā kā programmatūras funkcionalitāte parasti ir sarežģīta, uzziņu dokumenti parasti ir lieli. Attiecīgi, darbietilpība visu šo saišu manuālai uzturēšanai aug vismaz lineāri (bet parasti jau ģeometriskā progresijā) atkarībā no funkciju skaita.

Šī iemesla dēļ es uzskatu, ka ir ļoti svarīgi izmantot rīkus, kas ļautu

  • funkcionalitātes aprakstu glabāt repozitorijā, pret ko var veikt pieprasījumus, un tādējādi
    • viegli noskaidrot sistēmas iekšējās atkarības
    • identificēt kļūdas funkcionalitātes aprakstos (piemēram, lēmuma rombiņus, no kuriem neiziet neviena bulta)
  • no repozitorijas ģenerēt dokumentus
  • vēlams, ļautu saistīt funkcionalitātes aprakstu un darba uzdevumus issue tracking sistēmā, šādi nodrošinot trasējamību