Dokumentatsioon vananeb vaikselt

Keegi ei tee pilti “see leht on aegunud”. Aegunud dokumentatsioon kukub läbi vaikselt: keegi loeb seda, tegutseb selle järgi, saab veidi vale tulemuse ja järeldab, et dokumentatsioon üldiselt ei ole usaldusväärne. Pärast seda ta enam ei loe ja lehe vigasus ei jõuagi kellenigi, sest keegi ei vaata seda.

Huvitav küsimus ei ole “kuidas kirjutada paremat dokumentatsiooni”, vaid “kuidas saada teada, et leht on aegunud, ilma et inimene seda märkaks”.

Kaks asja, mis aitasid:

• Vananemise kontroll. Viimase muutmise aeg, omanik ja see, kas leht ikka kirjeldab seda, mida ta väidab kirjeldavat. Kõige hullemad on omanikuta lehed, sest kontrollil pole kelleltki küsida.
• Lugemiste arv, eraldi inimeste ja masinate kaupa. Confluence’i audit-logid eristavad inimest, kes lehe avab, ja CLI-d, mis selle alla laeb. See vahe on oluline: leht, mida masinad loevad palju ja inimesed üldse mitte, on agentide jaoks kandev ja kõigi teiste jaoks nähtamatu.

Teine muutis seda, kuidas ma esimesest mõtlen. Töö lehe kallal, mida keegi ei loe, on raiskamine — ja kuni sa lugemisi ei näe, sa lihtsalt oletad.