DOK-NOUDED.md

Nõuded üleantavale dokumentatsioonile

(mudeldokument)

Käesolev dokument esitab kogumi üldisi nõudeid ja soovitusi arendusprojektides Täitjate poolt Tellijale üleantavatele dokumentidele. Osa nõudeid võivad olla diskuteeritavad. Kõik nõuded ei tarvitse olla universaalselt rakendatavad. Nõuete ja soovituste osalise või täieliku kohaldamise projektis otsustab projektijuht. Nõudeid saab kohaldada ka asutusesiseselt. Arvamused ja ettepanekud on teretulnud (GitHub-i Issue ja Pull Request).

1. Üldine

   1. Üleantav dokumentatsioon peab moodustama ühtse terviku, seda nii sisu, struktuuri kui ka vormistuse poolest.
   2. Üldreeglina peab ka iga üksik dokument moodustama eraldikäsitletava terviku.

2. Tähtsus

   1. Dokumentatsiooni eesmärk on projekti tulemuste kindel fikseerimine ja teabe selge ning efektiivne kommunikatsioon erinevatele sihtrühmadele.
   2. Eelistatud on kompaktsed, põhjalikult ettevalmistatud, küsimusi sisuliselt käsitlevad ja asju seletavad, korrektselt vormistatud dokumendid, mida on ka kerge ajakohasena hoida.
   3. Dokumentatsioon ei tohi olla formaalne ega dokumentatsiooni suurele mahule orienteeritud.
   4. Arvestagem agiilse IT-arenduse põhimõttega Working software over comprehensive documentation, http://www.agilemanifesto.org/.
   5. Koodi kvaliteet ja dokumentatsiooni kvaliteet on võrdselt tähtsad.
   6. Programmeerimises on väljakujunenud praktika stiilijuhiste kasutamine (vt nt Google programmeerimise stiilijuhised). Täpselt samamoodi on kvaliteetse dokumentatsiooni loomiseks vaja vormistuslikke kokkuleppeid.

3. Vormivabadus

   1. Käesolevate nõuete kohaldamisel on esmatähtis nõude eesmärk ja mõte, mitte nõude vorm.
   2. Dokumendis on primaarne sisu, mitte vorm.
   3. Konkreetsele sisule asjakohase vormi leidmine on dokumendi koostaja ülesanne.
   4. Käesolevad nõuded ei kirjuta ette kivisseraiutud vorme, vaid pakuvad malle, mille kasutamine reeglina hõlbustab kommunikatsiooni.

4. Sisukorradokument

   1. Enamast kui ühest dokumendist koosneval dokumendipaketil peab olema eraldiseisev sisukorradokument (ingl Documentation Master List).
   2. Sisukorradokument peab sisaldama üleantavate dokumentide täielikku loetelu. Iga dokumendi kohta tuleb esitada (minimaalselt) nimetus, viimase versiooni number ja versiooni loomise kuupäev.
   3. Üleantava dokumentatsiooni komplekt, sh nimetused peavad vastama hankedokumendis, lepingus ja Tellijaga projekti käigus kokkulepitule.

5. Esileht

   1. Dokumendi tiitel- või esilehel esitatakse teave dokumendi Tellija ja Täitja kohta. Organisatsiooni (ettevõtte) nimi esitakse ametliku täisnimena.
   2. Üleantavat dokumenti ei vormistata ettevõtte blanketil ega ettevõtte kujundusmallil.

6. Logo

   1. Esi- või tiitellehele võib paigutada Täitja logo. Sellisel juhul paigutatakse esilehele ka Tellija (Riigi Infosüsteemi Ameti logo). Kui projektis on rohkem partnereid, siis paigutatakse kõigi logod.
   2. Logo ega autoriõiguse märget ei korrata esi- või tiitellehele järgnevatel lehekülgedel.
   3. Struktuuritoetuse abil rahastatud projektis tuleb dokumendi päisesse paigutada struktuuritoetuse logo. Juhised vt http://www.struktuurifondid.ee/kujundusfailid-20142020/.
   4. Näide: Ernst & Young (2013) Protsessianalüüsi käsiraamat, https://www.mkm.ee/sites/default/files/protsessianaluusi_kasiraamat.pdf.

7. Keel

   1. Dokument peab vastama õigekeelsusnormidele. Tekst peab olema keelelt ja stiililt korrektne. Märkus. IT erikeele üldtunnustatud tava võib mõnikord üldkeele normist lahkneda.
   2. Terminoloogia peab olema läbivalt ühtne. Vastavalt vajadusele lisatakse sõnaseletused või definitsioonid; kui neid on rohkem, siis eraldi jaotisena.
   3. Keelekasutus peaks olema vaba eesti keelele mitteomasest lausestruktuurist.
   4. Eelistatud on omakeelsed sõnad.
   5. Tuleb kasutada valdkonnas väljakujunenud terminoloogiat.
   6. Eestikeelsete IT oskussõnade leidmisel on autoriteetsete sõnastike hulgas:
      1. Andmekaitse ja infoturbe seletussõnastik (Cybernetica AS)
      2. Standardipõhine tarkvaratehnika sõnastik (Cybernetica AS)
      3. Heikki Vallaste E-sõnastik
   7. Muukeelseid IT-sõnastikke:
      1. ISTQB Glossary of Testing Terms
      2. ISO/IEC/IEEE 24765 Systems and software engineering — Vocabulary
   8. EL mitmekeelne terminibaas IATE.
   9. Asjakohases stiilis. Tehniline dokumentatsioon reeglina ametlikus stiilis. Vaba kantseliidist. Ametliku sisuga kirjaliku teksti toimetamisel on heaks abiliseks Ametniku soovitussõnastik.

8. Failinimed ja URL-id

   1. Failide nimed ja samuti URL-id peavad olema süsteemsed ja informatiivsed.
   2. Kui Tellija ei ole mustrit ette andnud, siis valib Täitja ise otstarbeka nimemustri.
   3. Versioneeritava dokumendi failinimetuses kaaluda versiooninumbri lisamist.
   4. Kuupäeva kasutamisel failinimes kasutada kuju AAAA-KK-PP (mitte AAKKPP, PP.KK.AAAA vms).
   5. Avalikult esitletavad failid peaksid saama inimesele kergesti loetavad nimed. Näiteks:
      1. https://www.ria.ee/public/RIA/Cryptographic_Algorithms_Lifecycle_Report_2016.pdf
   6. Kirjandus:
      1. European Commission (2012) 10 rules for persistent URIs

9. Nummerdamine

   1. Nummerdamise peamine eesmärk on dokumendi osistele viitamise hõlbustamine.
   2. Lehekülgede nummerdamisel on sageli kasu X (Y) kujust.

10. Kujundus

    1. Kujundus peab olema läbivalt ühtne.
    2. Kujunduse eeskujuks on Riigi Infosüsteemi Ameti asjaajamiskord. Asjaajamiskorra saab RIA-poolselt projektijuhilt.

11. Joonised

    1. Joonised üldreeglina nummerdatakse.
    2. Valitud tähistussüsteemid peavad arvestama lugejaskonna ettevalmistustaset. Vajadusel lisatakse legend või kasutatud tähistuste lahtiseletus.

12. Versioneerimine

    1. Üldreeglina dokumendid versioneeritakse. Soovitatav on järgida kokkulepet, et 0.n tähistab tööversiooni, 1.0 – valmisversiooni.
    2. Üldreeglina näidatakse versiooni numbriga koos ka versiooni valmimise kuupäev.
    3. Dokumente püütakse hoida ajakohasena.
    4. Vanad versioonid ja tähtsuse kaotanud dokumendid arhiveeritakse ja „kõrvaldatakse pildilt“.
    5. Dokumentides ja dokumentide kogumites järgitakse põhimõtet „kõige tähtsam esikohale“.

13. Kontekst

    1. Dokumendis tuleb esitada dokumendi mõistmiseks hädavajalik taustateave (dokumendi kontekst).
    2. Dokumendist peab olema võimalik aru saada, millise toote, süsteemi ja/või projekti juurde dokument kuulub. Standardseks võtteks on toote, süsteemi ja/või projekti nime selge väljatoomine, nt iga lehekülje päises.
    3. Üldreeglina tuleb dokumendis viidata teistele dokumentidele, mis on vajalikud dokumendi mõistmiseks. Viited peavad olema täpsed. Dokumendi nimetuse muutmisel tuleb ajakohastada ka viited dokumendile.

14. Eesmärk

    1. Kohe dokumendi alguses sõnastatakse lahendatav ülesanne ja/või dokumendi eesmärk.
    2. Vajadusel määratletakse dokumendi käsitlusala (skoop) ja sihtrühm(ad).

15. Struktuur

    1. Tekst liigendatakse otstarbekalt.
    2. Pikemas dokumendis koostatakse sisukord.

16. Dokumendivormingud

    1. Dokumendivormingute valikul lähtutakse eelkõige lugejate eelistustest.

17. Erinõuded

    1. Lähtudes dokumendi valdkonnast kohalduvad erinõuded ja/või valdkonna dokumenteerimise hea tava. RIA on käesolevaks ajaks välja töötanud järgmised erinõudeid määratlevad doku-mendid:
       1. arhitektuuri mall;
       2. protokollide spetsifitseerimise parim praktika;
       3. olemite-suhete andmemudeli dokumenteerimisnõuded.
    2. Dokumenteerimise erinõudeid sisaldavad dokumendid või viited nendele lisatakse hankedokumentidele.

18. Kvaliteedikontroll

    1. Üleantav dokumentatsioon peab olema läbinud tekstiredaktori õigekirjakontrolli ja/või inimtoimetaja kontrolli.
    2. Üleantav lõplik dokumentatsioon ei tohi sisaldada TODO märkmeid, töömärkmeid, muutuste jälitamise märkeid, veerukommentaare ega muid „lahtisi otsi“. Võimalikud lahendamata jäänud küsimused ja probleemid tuuakse välja eraldi jaotises.
    3. Tellijapoolne projektijuht kontrollib üleantavate dokumentide komplektsust ja vormistusnõuete täitmist.
    4. Vormistusnõuete täiemahuline järgimine on soovitatav juba projekti vältel Tellijale esitatavates kavandites, töö- ja vaheversioonides jms.