Ekilex on kasvanud juba päris keerukaks. Samas dokumentatsioon puudub peaaegu täiesti. Miks?
Kõigepealt mõned näited küsimustest, millele vastuste otsimiseks on viimasel ajal dokumentatsioonist puudust tuntud.
- Kas meil seosetüüp vt on olemas ja kui siis milliste olemite vahel?
- Mida sisaldavad viite väljad name ja value?
- Milliste võtmetega parameetreid esineb keelendi seostel?
- Miks on mitteavalikud sõnakogud Ekilexis avalikult näha?
- Mis vahet on märkusel ja kasutusnäitel või milleks nad mõeldud on?
- Kas leidub kohta, kuhu kirjutada termini usaldusväärsus?
Nagu näha, on need enamasti üsna detailsed küsimused, ja pigem arendaja või halduri kui lõppkasutaja tasemel. Ekilexi arenduse senine poliitika on olnud, et parim arendajadokumentatsioon on hästikirjutatud kood, millest pädev lugeja saab kohe aru, mida üks või teine funktsioon teeb. Ka andmebaasi tabelite ja väljade nimed on valitud inimloetavust silmas pidades.
Ainsad selle taseme asjad, mille kohta praegu on juhendeid kirjutatud, on API ehk rakendusliides väliste programmide jaoks, kus väline programm peab teadma, mida küsida, ja sellised protsessid nagu sõnakogude import, mille käivitaja peab teadma vajalikke samme ja nende parameetreid. Lisaks on avalikult kättesaadav arenduse saba ehk backlog Pivotal Trackeris.
Lõppkasutaja dokumentatsiooniga on algust tehtud, aga see on mu jaoks üldse omaette teema. Minu meelest ei tohiks tarkvara kasutamiseks juhendeid vaja minna. Esiteks tuleks kasutajaliidesed teha nii intuitiivseks, et kasutamisel küsimusi ei tekigi. Aga isegi kui tekib, on kasutajate harjumused viimasel ajal põhjalikult muutunud ja vastuseid otsitakse guugeldades, mitte juhendeid lugedes. Pealegi on konkreetselt sõnastikusüsteemi puhul kasutajatel puudu pigem leksikograafia või terminoloogia sisuteadmisi, et kuidas on üldse mõtet mingit nähtust esitada, mitte et millise nupuga seda selles konkreetses tootes teha saab.
Niisiis, arendajate ja haldurite küsimuste juurde tagasi tulles: miks ma ei soovi rohkem dokumentatsiooni kirjutada?
Küsimusi on võimatu ette näha
Vähemalt mina küll ei oleks enne ülalloetletud küsimuste laekumist osanud oletada, et just nendest tuleks dokumentatsioonis kirjutada. Isegi kui oleksin üritanud kirjutada absoluutselt kõigest, ei oleks nii spetsiifilised asjad pähe tulnud.
Eriti võimatu on ette näha küsimuste sõnastust
Tean küll, et näiteks ilmik ja selle kaal on selgitamist vajavad nähtused, kuna kumbagi ei ole varasemates sõnastikes ega terminibaasides niimoodi kasutatud. Ok, kirjutan juhendisse, et ilmik on seos sõna ja tähenduse vahel ja ilmiku kaal näitab selle seose tugevust. Inimene aga otsib termini usaldusväärsust, mitte ilmiku kaalu. See on sisuliselt täpselt sama asi, aga mul ei ole kuskilt võtta infot, et teda kunagi tulevikus just selles sõnastuses otsida võidaks. Ja loomulikult ei otsi keegi ilmikut, kuna keegi ei tea sellise asja olemasolustki.
Dokumentatsioon ei erine kuigivõrd oma algandmetest
Näiteks küsimus seoseliikide olemasolu ja kuuluvuse kohta. Nende liikide täielikud ja ajakohased loetelud on klassifikaatorifailides olemas. Nende kopeerimine dokumentatsioonifaili ei teeks neid kuidagi paremini leitavaks, küll aga tekiks uus praktiline probleem:
Dokumentatsioon vananeb vältimatult ja kiiresti
Eluline näide dokumentatsioonist, mis on küll olemas, aga pikalt ajakohastamata, on andmemudeli kirjeldus. Praegu seda selgitust kirjutades vaatasin ta üle ja tegin mõned parandused suuremate aegumiste järeleaitamiseks, aga enne seda oli ta üle kahe aasta muutmata. Nii andmemudel kui ka selle aluseks olevad sisulised seisukohad aga on samal ajal märkimisväärselt arenenud.
Miks teda siis uuendatud poldud? Sest pidevalt on kiire uue funktsionaalsuse saamise, järgmise versiooni avaldamise, vigade parandamise vms sisulise tööga. Arendusel on ees pikk järjekord selliseid soove ja ka endal kihk neid juba kiiremini täita. Asjad, millega ei ole päevapealt kiire, selle järjekorra etteotsa ei jõua. Dokumentatsiooni ajakohastamisega ei ole päevapealt kiire.
Olemasolevad vs puuduvad funktsioonid
Levinud viis küsimuste tekkimiseks on see, kui kasutaja otsib mingit funktsiooni või võimalust, ja ei leia. Väga sageli on siis vastus lihtsalt, et seda polegi (veel) tehtud. Nt ülalmainitud küsimus vt-viite olemasolust. Ei ole sellist. Miks, on eraldi küsimus, ja siin on rohkem variante: seda võib olla otsustatud mitte teha, see võib olla parajasti tegemisel või tulevikus tegemise järjekorras.
Probleem puuduvate funktsioonidega on, et nende loetelu on lõputu. Mõned neist on teada, need on kirjas arenduse sabas, aga ülejäänusid ei olegi kuskilt võtta. Selle kasutaja küsimus ise võibki olla päris esimene info niisuguse funktsiooni vajalikkuse kohta.
Dokumenteerimise töömaht
Tänapäeva programmikeelte ekspressiivsuse juures on ammendav dokumentatsioon vähemalt sama mahukas kui programm ise. Kõike tuleks siis kirjutada kaks korda: masinale, et mida teha, ja inimlugejale, et mida teeb.
Arenduse aeg on nii kallis ja selleks vajalikud oskused nii spetsiifilised, et minu meelest pole arendajaid mõtet sellise topeltkirjutamise peale raisata. Parem kaks töötavat funktsiooni kui üks põhjalikult dokumenteeritud töötav funktsioon.
Bugid, vead, ettenägematused, möödarääkimised
Seega võiks dokumenteerida keegi teine. Loogiline kandidaat on tooteomanik(ud), kes arendusele tellimusi vahendavad. Neil on sageli kõige parem ülevaade, mis on tehtud, mis tegemata, ja mis faasis igaüks viimastest on. Vähemalt nii me ise arvame.
Tegelikult pole üldse haruldased juhtumid, kus arendus saab tellimusest hoopis teistmoodi aru, kui tooteomanik mõtles. Näiteks järgmine päriselt juhtunud lugu.
Ekilexis saab andmete avalikkust määrata kolmel tasemel.
- Mõned andmetüübid pole kunagi avalikud, nt logid või sisemärkused.
- Koostaja saab ilmiku tasemel avalikkuse määrata kirjele või artiklile.
- Sõnakogu omanik saab määrata ka sõnakogu kui teviku avalikkuse.
Kõik kolm on tellitud, neist kolmas umbes sarnases sõnastuses nagu siin loendis, ja ka Ekilexis realiseeritud juba mõnda ega tagasi. Ühel hetkel aga selgus ootamatult, et võõrastel on võimalik näha ka mitteavalikke sõnakogusid. Uurimisel selgus, et tõepoolest, tellitud ja realiseeritud on just see, et sõnakogule saab avalikkuse määrata. Mitte et see määrang mõjutaks sõnakogu kuva Ekilexis.
Kasutaja küsis seepeale, kust ta pidi teadma, et see tegemata on, kui dokumentatsiooni pole? Just, seda minagi, kust oleks dokumenteerija pidanud seda teadma? Põhjus oli ju möödarääkimine sellesama potentsiaalse dokumenteerija ja arenduse vahel. Tooteomaniku jaoks avalikkuse mõte selles ongi, et mitteavalikke ei näidata avalikult, aga arenduse jaoks, nagu tagantjärele selgus, on need kaks selgelt erinevat funktsiooni: avalikkuse määramine ja selle määrangu mõju sõnakogude kuvamisele. Peaaegu nagu kvantmehaanika: möödarääkimisest teadasaamine teeb selle möödarääkimise olematuks.
Ei oleks ju mõtet sellele kasutajaküsimusele vastata, et Ekilexis sõnakogu avalikkuse linnuke sõnakogu avalikkust ei mõjuta. Ammugi poleks mõistlik (ega minu meelest ka võimalik) niisugust asja kirja panna juhendisse. Mõistlik vastus on, et oi tõepoolest, aitäh märkamast, parandame ära.
Kokkuvõtteks
Kõigile võimalikele küsimustele vastava dokumentatsiooni koostamine ei ole töömahu mõttes realistlik, paljudel juhtudel isegi mitte võimalik, ja kui ikkagi üritada koostada, siis mina kahtleksin ka tulemuse kasutuskõlbulikkuses. Juhendeid ei loe keegi. Paremini saab vastuseid koodist, andmebaasist, kontrollpäringutest, arenduse järjekorrast, või siis inimestega rääkides.