Her ekipte bir kişi vardır: aklında tuttuğu için dokümantasyon yazmayan, sonra işten ayrıldığında bilgiyle birlikte kapıdan çıkan. Onun gerisinde kalanlar, üç yıl önce alınmış bir kararın sebebini bilgisayarda değil, hafızada arar. Dokümantasyon sevmek, yazıyı sevmenin ötesinde bir sorumluluktur: Bugün bildiğimizi, yarın bizden sonra gelenin de bilmesi diye kayda geçmek. Yazılmamış bilgi, bir süre sonra herkesin bildiği ama kimsenin anlatamadığı bir söylentidir.

Gelecekteki Meslektaşımıza

İyi dokümantasyon, kendine konuşur gibi yazılır: Neden böyle yapıldı, hangi alternatif reddedildi, hangi tuzağa düşüldü. Kod "ne yaptığını" söyler; yazı "neden"i anlatır. Bu nedenle dokümantasyon, üç yıl sonraki kendimize yazılmış bir mektuptur. Mektubun alıcısı çoğu zaman biziz; üç ay sonra kendi kodumuza dönen kişi, bugünkü yabancıdan bir farkı olmayan bir okuyucudur. O yüzden yazının ölçüsü okurun bilgisi değil, yazarın unutma hızıdır. Bir proje sayfası, bir mimari karar kaydı, beş satırlık bir çalıştırma notu: hepsi, unutmanın üzerine atılan bir taş.

Kod, yazıldığı günün hırsıyla; dokümantasyon, okunacağı günün sabrıyla yazılır. İkisi birbirini telafi eder; biri eksildiğinde diğerinin açığı büyür.

Neden Yazmıyoruz

Yazmamak için üç klasik bahanemiz var: vaktin yokluğu, bilginin geçiciliği ve aracın kötüğü. Ama gerçek neden, bunların hiçbiri değildir; gerçek neden, yazının ölçülmemesidir. Toplantı, kod ve dağıtım ölçülür; yazılan belge, kimsenin dengesinde bir kalem değildir. Oysa bir yeni çalışanın ilk haftasında dokümantasyona borcu, çoğu zaman senior desteğinden fazladır. Bir diğer klasik bahaneyi de yıkalım: dokümantasyon güncelliğini yitirir. Evet, yitirir; ama güncel olmayan bir yazı, hiç olmayan yazıdan daha iyidir. Eksik yazı, düzeltilir; hiç yazı, yeniden keşfedilir.

Bir de bulunabilirlik meselesi var: Yazılan ama bulunamayan belge, yazılmamışla aynı etkiyi yapar. Belge, kişisel klasörlerde, dağınık depolarda ve sohbetlerin derinliklerinde kaybolur. Çözüm, tek bir yerde tek bir formattır: belge, projenin deposunda kodla birlikte durur ve kod değiştiğinde aynı gönderiyle güncellenir. Adresi belli olan yazı okunur; adresi belirsiz olan yazıya, bir daha uğranmaz. Dokümantasyona ayrılan arama süresi de bir maliyettir; kayıp belge, aramaya harcanan saatlerle geriye ödenir.

Az Yaz, Düzenli Yaz

Dokümantasyon sevgisi, ciltli kitap sevgisi değildir. Kısa, güncel ve bulunabilir yazı, uzun ve çürümüş yazıdan değerlidir. Öneri üç adımdır: Her projeye "nasıl çalıştırılır" ve "neden böyle yapıldı" diye iki sayfa açın. Her büyük kararın sebebini, e-posta değil, o projenin belgesine yazın. Ve dokümantasyona bakım, kodun bir parçası sayın: fonksiyonu değişen satırın, satır karşılığı bir notu olsun. Bu kadar. Yazı, geleceğe bırakılan tek aracıdır ve geleceğe en çok bu sadık kalır.