A műszaki dokumentáció mindig ugyanolyan, jól kiszámítható módon mond csődöt. Valaki két nyugodt hét alatt nagyon sokat ír belőle, aztán a rendszer megváltozik, senki nem frissíti, és egy éven belül a dokumentum teljes meggyőződéssel állít valótlant. Ettől a ponttól kezdve rosszabb, mint a semmi, mert aki hisz neki, olyan információ alapján cselekszik, ami már régen nem igaz.

A szokásos válasz erre az, hogy írjunk még többet, ez viszont csak felgyorsítja ugyanazt a kudarcot. A hasznos válasz az, hogy kevesebbet írunk, és megválogatjuk, mit, mert a szűk keresztmetszet nem az írásra fordított munka. A karbantartás az.

Az egyetlen tartós próba arra, hogy egy dokumentumnak létezniük kell-e egyáltalán: észreveszi-e bárki, amikor tévessé válik? Egy telepítési útmutatót használnak, ezért a hibái azonnal a felszínre kerülnek. Egy alrendszer húszoldalas leírását egyszer olvassák el, és a hibái tizennyolc hónappal később derülnek ki, amikor valaki már cselekszik alapján. Azok a dokumentumok, amelyeket senki nem használ, csendben rothadnak el, és pontosan ezeket érdemes meg sem írni.

Miért avul el

Három mechanizmus, és ezek közül csak az egyik a lustaság.

A dokumentáció távol él attól, amit leír. A kód módosítása nem azonos egy wikioldal módosításával, így a kettő összhangja azon múlik, hogy valakinek eszébe jut-e. Ez az emlékezés megbízhatóan cserben hagy minket, és minél messzebb ül a dokumentum a kódtól, annál gyorsabban.

A megvalósítást írja le a szándék helyett. Az a dokumentum, amelyik azt magyarázza, hogyan működik most egy komponens, minden egyes átalakítással érvényét veszti. Az, amelyik azt magyarázza, miért létezik a komponens, és milyen megkötést elégít ki, túléli, mert az indok sokkal ritkábban változik, mint a kód.

Senkinek nem gazdája. Az a dokumentáció, ami mindenkié, valójában senkié, és nincs olyan pillanat, amikor a pontossága bárkinek is a konkrét feladata lenne.

A megoldások következnek az okokból: tartsd a kód közelében, a mechanizmus helyett a szándékot írd le, és adj minden dokumentumnak névvel megnevezett felelőst, valamint olyan alkalmat, amikor valóban használják.

A műszaki dokumentáció, amit érdemes karbantartani

Négy dokumentum lefedi az érték nagy részét. Minden másnak igazolnia kell magát.

Egy README, amivel el tudsz indulni. Mi ez a projekt, hogyan kell beállítani, hogyan kell futtatni a teszteket, hogyan kell kiadni. Folyamatosan használják, ezért a hibái gyorsan kiderülnek. Ez a legjobb megtérülésű dokumentum bármelyik repository-ban, és egyben az, amit a leggyakrabban hagynak ott projektsablonként, amit soha senki nem szerkesztett át.

Egy architektúra-áttekintés. Melyek a nagy darabok, hogyan beszélnek egymással, és miért vannak szétválasztva. Egy oldal és egy ábra, ami az alakot írja le, nem a részleteket. Ritkán változik, és megválaszolja azt a kérdést, amit különben minden új fejlesztő maga rak össze abból, hogy mindent végigolvas.

Döntési feljegyzések. Rövid jegyzetek, amelyek rögzítenek egy döntést, a mérlegelt alternatívákat és a választás indokát. A szakmai szóhasználatban rendszerint Architecture Decision Recordnak, röviden ADR-nek hívják őket. Ezekhez csak hozzáfűzünk, frissíteni soha nem kell őket, és megelőzik az ismételt munka legdrágább fajtáját: azt, hogy egy már lezárt kérdést rosszul vitassunk meg újra, mert senki nem emlékszik arra a megkötésre, ami annak idején lezárta.

Runbookok arra, ami elromlik. A runbook a hibaelhárítási forgatókönyv: hogyan kell felismerni és megjavítani azokat a hibákat, amelyek valóban előfordultak nálatok. Közvetlenül egy incidens után íródik, amíg friss, és a következő incidensnél teszi le a vizsgát. Az a runbook, amit még soha senki nem követett végig, csak egy piszkozat.

Vedd észre, hogy ezek közül egyik sem azt írja le, hogyan működik a kód. Arra maga a kód való, és minden olyan szöveg, ami megduplázza, második igazságforrássá válik, ami előbb-utóbb ellent fog mondani az elsőnek.

Írj annak, aki fáradt és siet

A műszaki dokumentáció túlnyomó részét nyomás alatt olvassák, olyan valaki, akinek egészen konkrét kérdése van, gyakran munkaidőn kívül. Neki írj, ne annak, aki ráérősen olvasgat.

Előbb a válasz, utána a magyarázat. Aki hajnali kettőkor olvassa a runbookodat, először a parancsot akarja látni, és csak utána az indoklást. A válasz elé tett háttérmagyarázat olyan szerkezet, ami a szerzőnek kényelmes, és rajta kívül senkinek.

Legyél konkrét. Valódi parancsok, valódi útvonalak, valódi példaértékek. A „állítsd be a megfelelő környezeti változókat" nem utasítás, hanem egy utasítás leírása.

Mondd meg, mi fog elromlani. A hibajelenségek és az, ahogyan kinéznek, gyakran a legértékesebb tartalom, mert pontosan ezt éli át éppen az olvasó.

Tartsd olyan rövidre, hogy igaz maradhasson. Minden mondat karbantartási teher. Az az oldal, ami lefedi a szokásos esetet, és beismeri a saját korlátait, jobb annál a dokumentumnál, ami mindent lefed, és három helyen téves.

Ugyanaz a fegyelem, amitől egy oldal idézhetővé válik egy visszakereső rendszer számára, teszi használhatóvá egy kimerült kolléga számára is, és pontosan erről szól a nyilvános szövegekkel kapcsolatban az útmutatónk arról, miért rangsorol jól a tartalmad, mégsem idézi senki.

Hogyan tartsd életben

Tedd be a repository-ba. Az a dokumentum, ami a kóddal együtt utazik, ugyanabban a review-ban módosul, mint a kód, és ez az egyetlen mechanizmus, ami a kettőt megbízhatóan összhangban tartja.

Nézd át a code review során. Ha egy változtatás tévessé tesz egy dokumentumot, az ugyanolyan review-megjegyzés, mint bármi más. Ez a rendelkezésre álló legnagyobb hatású szokás, és semmibe nem kerül.

Teszteld, amit lehet. Azok a telepítési lépések, amelyek lefutnak egy pipeline-ban, megszűnnek vágyálom lenni. Ha a README-d azt állítja, hogy három paranccsal működő rendszert kapsz, akkor bizonyítsa ezt be egy job.

Törölj bátran. A téves dokumentum rosszabb a hiányzónál, mert megbíznak benne. Ha valami elavul, és senki nem fogja rendbe tenni, vedd ki, és jegyezd fel, mi veszett el vele.

Dátumozd azt, ami lejár. Mindennek, amiben verziószám, ár vagy külső függőség szerepel, dátumot kell viselnie, hogy az olvasó meg tudja ítélni, megbízhat-e még benne.

Mire való ez valójában

A dokumentáció az a mechanizmus, amitől a tudás megszűnik egyes embereken múlni. Ez az egész haszon, és ezért üzleti, nem pedig esztétikai érv szól amellett, hogy megírjuk.

Az a rendszer, amit csak egyetlen ember tud kiadni, pontosan annyi idő alatt áll helyre, amennyire az az ember elérhető. Az a komponens, amit senki nem tud megindokolni, vagy újraépül, vagy babonából megmarad. Mindkettő megjelenik megállapításként a technikai átvilágításban, mindkettő megnyújtja az új fejlesztők beillesztését, és mindkettő ugyanaz a probléma, csak más ruhában.

A Mecanik minden megbízásnál az átadás részeként írja meg ezeket a dokumentumokat, a szoftverfejlesztési munkánk részeként. Az a dokumentum, amit végül használnak, szinte mindig rövidebb annál, mint amit megrendeltek.

Gyakran ismételt kérdések

Miért avul el a műszaki dokumentáció? Mert távol él a kódtól, így az összhang azon múlik, hogy valakinek eszébe jut-e; mert a megvalósítást írja le a szándék helyett, így minden átalakítás érvényteleníti; és mert nincs gazdája, így a pontossága soha nem lesz senkinek a konkrét feladata. Ha a repository-ban tartod, és a kódváltozásokkal együtt nézed át, mind a három okot egyszerre kezeled.

Milyen dokumentációt tartson karban egy szoftvercsapat? Négy dolog lefedi az érték nagy részét: egy README, amivel elindul a rendszer, egy egyoldalas architektúra-áttekintés az alakról és az indoklásról, csak bővülő döntési feljegyzések arról, miért születtek az egyes döntések, és runbookok azokra a hibákra, amelyek valóban előfordultak. Annak leírása, hogyan működik a kód, nincs a listán.

Mi az a döntési feljegyzés? Rövid jegyzet, ami rögzít egy döntést, a mérlegelt alternatívákat és a választás indokát. Mivel egy pillanatot rögzít, nem pedig az aktuális állapotot, soha nem kell frissíteni, és megakadályozza, hogy lezárt kérdéseket rosszul vitassanak meg újra olyanok, akik már nem emlékeznek a lezáró megkötésre.

Hogyan kell műszaki dokumentációt írni? Annak, aki fáradt, nyomás alatt van, és egyetlen konkrét dolgot keres. Előbb a válasz, utána a magyarázat, valódi parancsok és valódi útvonalak a leírásuk helyett, mondd meg, mi romlik el és hogyan néz ki, és tartsd olyan rövidre, hogy igaz maradjon.

Törölni kell az elavult dokumentációt? Igen, ha senki nem fogja rendbe tenni. A téves dokumentum rosszabb a hiányzónál, mert az olvasó megbízik benne, és aszerint cselekszik. Töröld, és jegyezd fel, mi veszett el, és dátumozz mindent, amiben verziószám, ár vagy külső függőség szerepel, hogy az olvasók maguk ítélhessenek.