Documentația tehnică eșuează într-un mod precis și previzibil. Cineva scrie foarte multă în două săptămâni liniștite, sistemul se schimbă, nimeni nu o mai actualizează, iar într-un an documentul afirmă cu toată convingerea lucruri false. Din acel punct e mai rău decât nimic, pentru că cine se încrede în el acționează pe informații care nu mai sunt valabile.

Reacția obișnuită este să se ceară mai multă documentație, ceea ce nu face decât să accelereze același eșec. Reacția utilă este să scrii mai puțin și să alegi ce anume, pentru că limitarea nu este efortul de a scrie. Este întreținerea.

Singurul test durabil pentru a ști dacă un document merită să existe: va observa cineva când devine greșit? Un ghid de deployment este folosit des, așa că erorile lui ies la iveală imediat. O descriere de douăzeci de pagini a unui subsistem este citită o singură dată, iar erorile ei ies la iveală optsprezece luni mai târziu, când cineva acționează pe baza lor. Documentele pe care nu le exersează nimeni putrezesc în tăcere, și tocmai acelea trebuie lăsate nescrise.

De ce se învechește

Trei mecanisme, și doar unul dintre ele este lenea.

Documentația stă departe de lucrul pe care îl descrie. O modificare în cod nu este o modificare într-o pagină de wiki, așa că alinierea lor depinde de faptul că își amintește cineva. Memoria aceea cedează, constant, iar cu cât documentul stă mai departe de cod, cu atât cedează mai repede.

Descrie implementarea în loc de intenție. Un document care explică felul în care funcționează acum o componentă este invalidat de fiecare refactorizare. Unul care explică de ce există componenta și ce constrângere satisface supraviețuiește, pentru că motivul se schimbă mult mai rar decât codul.

Nu are stăpân. Documentația care aparține tuturor nu aparține nimănui, iar nu există niciun moment în care corectitudinea ei să fie problema cuiva anume.

Remediile decurg din cauze: ține documentația aproape de cod, scrie intenția în loc de mecanism și dă fiecărui document un responsabil cu nume, plus un prilej în care chiar este folosit.

Documentația tehnică pe care merită să o întreții

Patru documente acoperă cea mai mare parte a valorii. Tot restul trebuie să se justifice.

Un README care te pune pe picioare. Ce este proiectul, cum îl configurezi, cum rulezi testele, cum îl lansezi. Este folosit tot timpul, deci greșelile ies repede la suprafață. Este documentul cu cel mai bun randament din orice repository și, în același timp, cel lăsat cel mai des ca șablon de proiect pe care nu l-a editat nimeni.

O privire de ansamblu asupra arhitecturii. Care sunt piesele mari, cum comunică între ele și de ce sunt separate. O pagină și o diagramă, care descriu forma, nu detaliul. Se schimbă rar și răspunde la întrebarea pe care altfel fiecare coleg nou și-o reconstruiește singur citind tot.

Fișele de decizie. Notițe scurte care consemnează o decizie, alternativele luate în calcul și motivul alegerii. În jargonul tehnic li se spune de obicei Architecture Decision Record, pe scurt ADR. Se adaugă și nu se actualizează niciodată, iar ele previn cea mai scumpă formă de muncă repetată: redeschiderea prost a unei chestiuni deja lămurite, pentru că nimeni nu mai ține minte constrângerea care a lămurit-o.

Runbook-uri pentru ce se strică. Un runbook este procedura de intervenție: cum diagnostichezi și repari defecțiunile pe care chiar le-ai avut. Se scrie imediat după un incident, cât timp e proaspăt, și se pune la încercare la următorul. Un runbook pe care nu l-a urmat nimeni este o ciornă.

Niciunul dintre aceste patru documente nu descrie felul în care funcționează codul. Pentru asta există codul, iar orice text care îl dublează devine o a doua sursă de adevăr care va ajunge să o contrazică pe prima.

Scrie pentru cineva obosit și grăbit

Cea mai mare parte a documentației tehnice este citită sub presiune, de cineva cu o întrebare precisă, adesea în afara programului. Scrie pentru cititorul acela, nu pentru unul care are timp.

Întâi răspunsul, apoi explicația. Cine îți citește runbook-ul la două noaptea are nevoie de comandă, iar abia după aceea de raționament. Contextul înaintea răspunsului este o structură care îi convine autorului și nimănui altcuiva.

Fii concret. Comenzi reale, căi reale, valori de exemplu reale. „Configurați variabilele de mediu corespunzătoare" nu este o instrucțiune, ci descrierea unei instrucțiuni.

Spune ce o să meargă prost. Modurile de defectare și felul în care arată sunt adesea conținutul cel mai valoros, pentru că exact asta trăiește cititorul în acel moment.

Ține-o destul de scurtă cât să rămână adevărată. Fiecare frază este o datorie de întreținere. O pagină care acoperă cazul obișnuit și își recunoaște propriile limite bate un document care acoperă tot și greșește în trei locuri.

Aceeași disciplină care face o pagină citabilă pentru un sistem de regăsire o face utilizabilă pentru un coleg epuizat, și exact asta susține ghidul nostru despre de ce conținutul tău se clasează, dar nu e citat niciodată în privința textelor publice.

Cum o ții în viață

Pune-o în repository. Un document care călătorește împreună cu codul este modificat în același review ca și codul, iar acesta este singurul mecanism care le ține pe amândouă aliniate în mod fiabil.

Verific-o la code review. Dacă o modificare face un document greșit, asta este un comentariu de review ca oricare altul. Este obiceiul cu cel mai mare efect de pârghie disponibil și nu costă nimic.

Testează ce se poate testa. Instrucțiunile de instalare care rulează într-o pipeline încetează să mai fie o dorință. Dacă README-ul tău susține că trei comenzi produc un sistem funcțional, pune un job să dovedească asta.

Șterge fără regrete. Un document greșit este mai rău decât unul lipsă, pentru că lumea se încrede în el. Când ceva se învechește și nimeni nu îl va repara, scoate-l și notează ce s-a pierdut.

Datează ce expiră. Orice conține un număr de versiune, un preț sau o dependență externă ar trebui să poarte o dată, ca cititorul să poată judeca dacă se mai poate încrede în el.

La ce folosește de fapt

Documentația este mecanismul prin care cunoașterea încetează să depindă de persoane. Acesta este întregul beneficiu și de aceea argumentul pentru a o scrie este unul de afaceri, nu unul estetic.

Un sistem pe care doar o singură persoană știe să îl lanseze are un timp de revenire egal cu disponibilitatea acelei persoane. O componentă pe care nimeni nu o poate justifica ajunge fie refăcută, fie păstrată din superstiție. Ambele apar ca observații în due diligence tehnic, ambele prelungesc integrarea dezvoltatorilor și ambele sunt aceeași problemă îmbrăcată diferit.

Mecanik scrie aceste documente ca parte din predarea proiectului, la fiecare colaborare, ca parte din activitatea noastră de dezvoltare software. Documentul care ajunge să fie folosit este aproape întotdeauna mai scurt decât cel care fusese cerut.

Întrebări frecvente

De ce se învechește documentația tehnică? Pentru că stă departe de cod, așa că alinierea depinde de faptul că își amintește cineva; pentru că descrie implementarea în loc de intenție, așa că fiecare refactorizare o invalidează; și pentru că nu are stăpân, așa că exactitatea ei nu este niciodată problema concretă a cuiva. Ținerea ei în repository și verificarea odată cu modificările de cod rezolvă toate cele trei cauze.

Ce documentație ar trebui să întrețină o echipă de software? Patru lucruri acoperă cea mai mare parte a valorii: un README care pune sistemul în funcțiune, o privire de ansamblu asupra arhitecturii pe o pagină, care explică forma și raționamentul, fișe de decizie la care doar se adaugă, ce consemnează de ce au fost făcute alegerile, și runbook-uri pentru defecțiunile pe care chiar le-ați avut. Descrierile felului în care funcționează codul nu sunt pe listă.

Ce este o fișă de decizie? O notă scurtă care consemnează o decizie, alternativele luate în calcul și motivul alegerii. Pentru că înregistrează un moment, nu o stare curentă, nu are nevoie niciodată de actualizare și împiedică redeschiderea proastă a unor chestiuni deja lămurite de către oameni care nu mai țin minte constrângerea care le-a lămurit.

Cum ar trebui scrisă documentația tehnică? Pentru cineva obosit, sub presiune și care caută un singur lucru anume. Întâi răspunsul și apoi explicația, comenzi reale și căi reale în loc de descrieri ale lor, spune ce merge prost și cum arată, și ține totul destul de scurt cât să rămână adevărat.

Ar trebui ștearsă documentația învechită? Da, dacă nu o va repara nimeni. Un document greșit este mai rău decât unul lipsă, pentru că cititorul se încrede în el și acționează pe baza lui. Șterge-l și notează ce s-a pierdut, iar tot ce conține un număr de versiune, un preț sau o dependență externă datează-l, ca cititorii să poată judeca singuri.