Eleborarea documentației

Eleborarea documentației este un fel de cenușăreasa etapelor de eleborarea produselor softwareintea tuturor celor care participă la realizarea produsului este încolțită ideia că și fără documentație produsul funcționează. Adevărul nu este departe de această afirmație, numai că fără documentație programul e program, dar:

- funcționează greu;

- are limitări severe;

- nu e independent de cel care l-a scris;

- se consumă resurse în plus;

- funcționează cu costuri ridicate;

- funcționează pe bani mulți;

- uneori chiar nu funcționează deloc.

Am scris și eu ceva programe și n-aș zice că în vremurile de demult aveam o plăcere diabolică în a scrie documentație pentru că:

- toate lucrurile mi se păreau cunoscute;

- aveam impresia că n-am să uit nimic;

- credeam la început că este inutilă;

- nu vedeam utilitatea ei pe loc;

- credeam că mentenanța e floare la ureche;

- nu mi-o impunea nimeni dintre cei din jur;

- nici șefii nu prețuiau documentația;

- conținea o reflectare inutilă a programului;

- disprețuiam scrierea de proză;

- o vedeam inutilă că puneam comentarii în program;

- aveam senzația că nu o citea nimeni.

Când peste ani au început să apară procese de mentenanță și nu mai regăseam:

- formule,

- descrieri de câmpuri,

- condiții,

- particularități,

- semnificații coduri selecție,

- cerințe imperative,

reconstituirile din memorie sau întrebându-i pe alții erau deja un chin. În timp, m-am consolat cu ideia de a scrie documentație și acum vreo 5 ani am aruncat niște volume în care am descris la nivel de bloc de schemă logică programe pe care le-am făcut pentru niște beneficiari și care erau scoase din uz de destul de mult timp. Dacă atunci aș fi avut în gând să scriu o istorie a informaticii aș fi păstrat măcar un volum să arăt cum făceam eu documentație, fără a avea un standard, ci doar după cum mai făceau și alții care știau ei ce știau despre dificultățile de a face mentenanță. Mai până anul trecut am păstrat și cartelele unor programe, dar le-am aruncat la topit. Acum îmi pare rău. Trebuie să precizez că documentația conținea în acele vremuri date despre:

- contractul sub care s-a construit produsul software;

- echipa care a lucrat cu semnături;

- descrierea problemei;

- datele de intrare cu machete de cartele;

- datele de ieșire cu structuri de capete de tabel;

- la date se precizau tipul și formatul de perforat sau de tipărit;

- formulele de calcul în clar;

- schema de sistem;

- tabele de analiză utilizare câmpuri;

- algoritmii de prelucrare pe pași;

- scheme logice;

- descrierea de module și parametrii;

- lista mesajelor de eroare și cum se depanează;

- textul sursă;

- necsar minim de resurse;

- formule de calcul ale dimensiunilor problemelor de rezolvat;

- rezultate ale testării;

- modul de implementare;

- ghidul utilizatorului.

Nu cred că azi este o mare bucurie pentru programatori să scrie documentație, numai că acum există instrumente care:

- desenează scheme logice;

- extrag comentariile din programe;

- construiesc liste de variabile și obligă la completarea lor;

- fac sinteze la secvențele omogene ale programului;

- extrag listele de proceduri și impun descrerile lor;

- imun descrierile listelor de parametri;

- construiesc liste de variabile și impun descrierea lor;

- identifică unele imperfecțiuni din program.

Toate acestea îl forțează pe cel ce scrie documentație să fie extrem de atent și să realizeze descrieri corecte și complete, căci unele dintre instrumente fac și analiză de text introdus de cel ce face documentația și atenționează la atingerea unui nivel de redundanță prea ridicat, mai ales dată de repetarea prin copy-paste a unor paragrafe.

În opinia mea, a face documentația este un lucru esențial mao ales de când beneficiarii îi poartă prin tribunale pe dezvoltatori. De aceea, dezvoltatorii trebuie să facă ochiimaridacă trec sau nu elaborarea de documentație acolo în mod expre, dacă folosesc termenul de mentenanță care presupune documentație și dacă vorbesc cumva de audit, care trebuie făcut și un prim pas este acolo verificarea existenței specificațiilor, textului sursă și a documentației.
Eleborarea documentației este la fel de grea ca scrierea programului, dacă nu chiar mai grea, dacă se face 100% după ce programul  e gata de implementare și programatorul a neglijeat să facă notișe, a lucrat fără specificații și soluția a rezultat doar din discuții nu și dintr- schemă de sistem.

(29 noiembrie 2017)