Documentation Rot: Wiki'niz Neden 6 Ayda Çöküyor?
Mühendislik wikileri hızla çürür. Bu adli zaman çizelgesi, documentation rot'un tam olarak nasıl başladığını ve hangi sistemlerin önlediğini gösteriyor.
By Ellis Keane · 2026-04-07
Her mühendislik ekibinin, ekibin kurulduğu yıl moda olan belgeleme aracında (Notion çalışma alanı, Confluence örneği, GitHub wiki veya her neyse) "Service Architecture Overview" gibi bir başlıkla, on bir ay önce artık orada çalışmayan biri tarafından son kez düzenlenen bir sayfası vardır. O sayfa bir belge değil, bir fosildir ve onu fosile dönüştüren documentation rot, yazıldığı günün hemen ardından – yani herkesin "bunu güncel tutmak gerçekten önemli" üzerinde mutabık kaldığı gün – başlamıştır.
Wiki sayfası her şey hareket ederken yerinde donup kalıyor. Kimse silmiyor, çünkü silmek yıkıcı geliyor. Kimse güncellemiyor, çünkü güncellemek başkasının işi gibi görünüyor. Öylece orada duruyor, yetkili görünüyor, yavaş yavaş kurguya dönüşüyor. attribution: Ellis Keane
Documentation rot'u genellikle bir disiplin sorunu olarak ele alırız – sanki mühendislerin sayfaları güncel tutmaya daha fazla önem vermesi gerekiyormuş gibi, sanki asıl darboğaz mimari değil de motivasyonmuş gibi. Ancak konuştuğumuz ekiplerde bu kalıbın nasıl tekrarlandığını izledikten sonra (dürüstçe söylemek gerekirse, hiçbirinden muaf olmadığımız kendi küçük operasyonumuzda da), başarısızlık hep aynı: belgeler bir yerde, kod değişiklikleri başka bir yerde ve aralarında bağlantı kuran hiçbir sistem yok. Bu önem vermemekle ilgili değil. Belgelemenin nasıl çalıştığı ile mühendislik işinin gerçekte nasıl aktığı arasındaki temel uyumsuzlukla ilgili – ve bu uyumsuzluk için henüz yalnızca sürece dayalı bir çözüm bulamadık, uğraşmaya devam etmemize rağmen.
Bir Wiki Sayfasının Adli Zaman Çizelgesi
Aşağıdakiler mühendislik ekipleriyle yapılan görüşmelerden ve (üzülerek söylüyorum) kendi deneyimimizden derlenen bileşik bir tablodur; ancak dizi kuruluşlar arasında o kadar tutarlı ki ayrıntılar neredeyse önem taşımıyor. Dahili bir belge parçasına gerçekte ne olduğunu, oluşturulduğu andan güvenildiği için birinin yanlış karar verdiği ana kadar aktarayım.
title: "Bir Wiki Sayfası Nasıl Tehlikeli Hale Geldi" Gün 1|ok|Mühendis, büyük bir yeniden yapılandırmanın ardından "Payment Service Architecture"ı yazıyor. Doğru, ayrıntılı, sıralı diyagramlar içeriyor. Gün 14|ok|İki geliştirici, işe alıştırma sürecinde sayfaya başvuruyor. Saatlerce zaman kazandırıyor. Sayfa bir başarı gibi hissettiriyor. Gün 31|amber|Bir takım arkadaşı payment service'teki yeniden deneme mantığını yeniden düzenliyor. PR birleştiriliyor. Kimse wiki sayfasını düşünmüyor. Gün 45|amber|Ekip, paylaşılan bir Postgres örneğinden ayrılmış bir örneğe geçiyor. Wiki sayfasının veritabanı bağlantısı bölümü artık var olmayan altyapıyı tanımlıyor. Gün 72|amber|Yeni bir mühendis sayfayı okuyor ve belgelenen veritabanı yapılandırmasına göre yerel ortamını kuruyor. Çalışmıyor. Bir iş arkadaşı "o sayfa güncel değil" diyene kadar öğleden sonranın tamamını hata ayıklamakla geçiriyor. Gün 90|missed|Sabah 2'de bir olay yaşanıyor. Nöbetçi mühendis, servisin tırmanma yolu için wiki sayfasına başvuruyor. Listelenen sorumlu iki ay önce şirketten ayrılmış. Doğru kişiyi bulmak için yirmi dakika kaybediliyor. Gün 180|missed|Sayfa altı ayda onlarca kez görüntülenmiş. Birinci günden bu yana sıfır kez düzenlenmiş. Her bölüm en az bir hata içeriyor. Hangi bölümlerin hâlâ doğru olduğunu kimse bilmiyor.
Beşten fazla mühendis bulunan bir ekipte çalıştıysanız, bu zaman çizelgesinin bir versiyonunu muhtemelen yaşamışsınızdır. Şu an "bunun için bir sürecimiz var" diyerek başınızı sallıyorsanız, kendi wikinizin son değiştirilme tarihlerini kontrol etmenizi kibarca öneririm. Ayrıntılar farklı olabilir (belki mimari belgeler yerine API referansıdır, belki Notion yerine Confluence'dır, belki olay sabah 2 yerine 3'te olmuştur) – ama bozulma eğrisi her zaman, inatla aynı kalıyor.
"Belgeleri Sadece Güncelle" Neden Hiç İşe Yaramaz
Documentation rot'a verilen en yaygın yanıt süreçtir: "PR kontrol listesinin bir parçası olarak belgeleri güncellemeliyiz." Makul geliyor ve deneyimimize göre çoğu zaman başarısız oluyor; teşvik yapısını izlediğinizde nedenleri açıkça görünüyor. Bir mühendis günün sonundan önce bir değişikliği gözden geçirmeye, birleştirmeye ve dağıtmaya çalışırken (ve günün sonu her zamankinden hızlı geliyor), az önce değiştirdiği bileşene dolaylı olarak atıfta bulunan belgeler sayfası en iyi ihtimalle zihninin arka köşesinde belirsiz bir farkındalık, en kötü ihtimalle gerçekten varlığından haberdar olmadığı bir şeydir. CI iş akışı yeşile döner, PR birleştirilir ve kimsenin iş akışı "şimdi eski davranışı dolaylı olarak varsayan her wiki sayfasını bul" adımını içermez.
Ve kimsenin yüksek sesle söylemek istemediği kısım şu: sayfayı hatırlasalar bile, neyin özellikle değişmesi gerektiğini çoğunlukla bilmiyorlar. Bir kod değişikliği ile belgeleme sonuçları arasındaki ilişki her zaman açık değil. Yeniden düzenlenmiş bir fonksiyon imzası, o fonksiyonu adıyla belirtmeyen üç farklı wiki sayfasını geçersiz kılabilir.
Documentation rot dikkatsizlikten kaynaklanmıyor. Kod değişiklikleri ve belge değişikliklerinin tamamen farklı araçlarda, tamamen farklı zamanlarda, tamamen farklı teşvik yapılarıyla gerçekleşmesinden kaynaklanıyor. Aralarındaki bağlantı tamamen insan belleğinde tutuluyor; insan belleği ise dolaylı bağımlılıkları izlemek için güvenilir bir sistem değil.
Documentation Rot'un Üç Aşaması
Belgeler bir gecede doğrudan tehlikeliye dönüşmüyor – ve bu da tam olarak onu bu kadar sinsi yapan şey. Üç farklı aşamadan geçiyor, her biri bir öncekinden daha zor tespit edilen; ve hiçbir noktada kimse "hey, bu sayfa artık insanlara yalan söylüyor" diyen bir bildirim almıyor.
İlk aşama kozmetik kaymadır – haftalarca içinde başlar. Bir değişken adı değişir, bir URL yolu güncellenir, "Sahip" alanındaki takım üyesinin adı bir yeniden yapılanmanın ardından yanlış olur. Temel bilgiler hâlâ genel olarak doğru ve sayfayı okuyan biri ayrıntılar değişmiş olsa da doğru genel fikri edinebilir. Henüz hiçbir şey bozulmuş hissettirmiyor (ve bu noktada neredeyse hiç etmiyor), bu yüzden kimse düzeltmiyor; çünkü kozmetik açıdan kaymış bir wiki sayfasını düzeltmek mühendislikte diş ipiyle diş temizlemek gibi: herkes bunun önemli olduğunu kabul ediyor, kimse bugün yapmıyor.
Ardından genellikle birinci ile üçüncü aylar arasında yapısal sapma geliyor – mimarinin kendisi sayfanın tanımladığının ötesine geçiyor. Belki servis ikiye bölünmüştür, ya da bir uç nokta kullanımdan kaldırılmış ve tamamen farklı bir sözleşmeye sahip bir uç noktayla değiştirilmiştir, ya da kimlik doğrulama akışı tamamen değişmiştir. Bu aşamada sayfa aktif olarak yanıltıcı ama hâlâ yetkili görünüyor (diyagramları var, başlıkları var, açıkça ne hakkında konuştuğunu bilen biri tarafından yazılmış), bu yüzden okuyucular gereğinden uzun süre güveniyor – bu da gerçekten tehlikeli olan kısım.
Üç ile altı ay arasında tehlikeli kurguya ulaşıyorsunuz. Sayfa artık var olmayan bir sistemi tanımlıyor. Listelenen uç noktalar 404 döndürüyor. Veritabanı şeması iki kez taşınmış. Tırmanma yolu, bu noktada farklı bir şirkette çalışan ve muhtemelen servisin var olduğunu unutmuş olan birine götürüyor.
stat: "Sıfır düzenleme" headline: "Altı ay boyunca" source: "Mühendislik wikilerinde gözlemlenen kalıp"
Bu aşamada documentation rot'tan kaynaklanan hasar teorik değil. Mühendisler, açıkça söylemek gerekirse biçimlendirilmiş kurgu olan belgelere dayanarak dağıtım kararları, olay müdahale kararları ve işe alıştırma kararları alıyor.
Bozulmayı Gerçekten Yavaşlatan Şeyler
Süreç kontrol listeleri işe yaramıyorsa (ve yukarıda açıklanan yapısal nedenlerle yaramıyor), ne işe yarıyor? Dürüst yanıt şu: hiçbir şey documentation rot'u tamamen ortadan kaldırmıyor; ancak bazı ekipler onu yeterince yavaşlatmayı başarıyor, böylece bir wiki sayfasının yarı ömrü haftalardan aylara uzanıyor – bu "zaman zaman yanıltıcı" ile "aktif olarak tehlikeli" arasındaki fark. Konuştuğumuz ve en iyi performans gösteren ekipler birkaç ortak kalıbı paylaşıyor.
Kodun yanında yaşayan belgeler. Repoda README'ler, satır içi yorumlar, mimari karar kayıtları (ADR'ler) tanımladıkları kodun yanına işlenmiş. Bunların doğal bir avantajı var: kod değiştiğinde, belgeler aynı diff içinde mühendise bakıyor. Güncelleneceği garanti değil (hiçbir şey garanti değil), ancak yakınlık tek başına bunu önemli ölçüde daha olası kılıyor.
Otomatik eskime tespiti. Bazı ekipler, 90 gün boyunca düzenlenmeyen wiki sayfalarını işaretleyen basit bir betik çalıştırıyor. Ham, ama 3. aşama başlamadan önce sorunu yüzeye çıkarıyor. Mekanik ilkeden daha az önemli: belge doğruluğuna ölçülebilir bir şey olarak davranın, sadece ummayın.
Daha az, daha kısa belgeler. 3.000 kelimelik bir mimari genel bakış, belirli bileşenler hakkında odaklanmış beş yüz kelimelik üç sayfadan daha hızlı çürür. Daha küçük yüzey alanı, her sayfada yanlış gidebilecek daha az şey olduğu ve güncelliğini korumaktan sorumlu kişinin sayfanın tamamını gerçekten aklında tutabileceği anlamına geliyor.
Bozulmayı yavaşlatan şeyler
- Koda yakın belgeler – Aynı PR'da güncellenen repodaki README'ler ve ADR'ler
- Eskime uyarıları – 90 gün dokunulmayan sayfalar için otomatik işaretler
- Küçük, odaklanmış sayfalar – Çürümenin tutunması için daha az yüzey alanı
İşe yaramayanlar
- PR kontrol listeleri – "Belgeleri güncelle" onay kutusu eylem olmadan işaretleniyor
- Belgeleme sprintleri – Bir ay içinde çürüyen bir haftalık güncellemeler
Daha Derin Sorun: Belgeler Bir Anlık Görüntü, İş Bir Akıştır
Yukarıdaki düzeltmelerin hepsi hafifleticidir ve bunu dürüstçe kabul etmeliyiz. Altta yatan sorun şu: belgeler doğası gereği sürekli değişen bir şeyin belirli bir andaki anlık görüntüsü; ve ne kadar süreç katmanı eklersek ekleyelim bu temel gerilimi değiştiremeyiz. Bugün sistemin nasıl göründüğünü yazıyorsunuz, yarın sistem farklı, belgeler çoktan çürümeye başlamış ve kimse birinin zarar görene kadar fark etmeyecek.
Bu sorunla en az mücadele eden ekipler (ve "en az"ın nasıl göründüğünü hâlâ çözmeye çalışıyoruz – çünkü bunu gerçekten kimse çözmedi) statik belgelerden canlı, sorgulanabilir bağlama geçenler. "Ödeme servisi platform ekibine ait" yazmak yerine "ödeme servisi üzerinde son zamanlarda kim çalıştı?" sorusunu gerçek commit'lere, PR'lara ve gerçek kararların alındığı Slack tartışma zincirlerine bakarak yanıtlayabilen araçları var.
Somut olarak bu, CODEOWNERS'tan ve son commit yazarlarından türetilen sahiplik, CI'dan çekilen dağıtım geçmişi, çağrı cihazı günlüklerinden aranan olay müdahale görevlileri ve bağlantılı Linear sorunlar ile Slack tartışma zincirleri aracılığıyla izlenen karar bağlamı anlamına geliyor. Bu bir wiki değil ve bu terimin geleneksel anlamında bilgi yönetimi de değil. Canlı bir dizin – çünkü insanların zaten kullandığı araçlardan çekiyor; kaçınılmaz ve öngörülebilir biçimde çürüyecek ayrı bir nesneyi güncel tutmalarını istemiyor.
En güvenilir belgeler, kimsenin yazmak zorunda olmadığı belgelerdir. Bağlam, işin gerçekte gerçekleştiği araçlardan (kod depoları, sorun izleyiciler, iletişim kanalları) çekildiğinde çok daha yavaş çürür; çünkü gerçekte olanı yansıtır, birinin yazmayı hatırladığını değil.
Geleneksel Belgelere Gerçekten Ne Zaman İhtiyaç Duyulur
Bunların hiçbiri wikilerin işe yaramaz olduğu anlamına gelmiyor. Gerçekten bir insan tarafından yazılmaktan, kasıtlı olarak bakımı yapılmaktan ve düz yazı olarak saklanmaktan fayda gören belirli belge kategorileri var:
- İşe alıştırma kılavuzları – mimari kararların "neden"ini açıklayan, yalnızca "ne"yi değil
- Çalışma kitapları – olay müdahalesi için; izleyicinin sabah 2'de kontrol listesine ihtiyaç duyan stresli bir mühendis olduğu, bilgi grafiği sorgusu değil
- Uyumluluk belgeleri – yapılandırılmış, sürümlü eserler bekleyen denetçiler tarafından istenen
- Genel API referansları – harici geliştiriciler tarafından kullanılan
Temel ayrım: bu belgeler yavaş değişen şeyleri (şirket değerleri, uyumluluk gereksinimleri, genel sözleşmeler) ya da anlatı bağlamının mevcut doğruluktan daha önemli olduğu şeyleri (üç yıl önce neden DynamoDB yerine Postgres seçtik) tanımlıyor.
Her şey için (kimin ne sahip olduğu, mevcut mimari nedir, bu karar nerede alındı), yanıt altı ay önce birinin yazdığı wiki sayfası olmamalı. Gerçekte ne olduğuna karşı bir sinyal sorgusu olmalı.
Sinyal istihbaratını gelen kutunuza alın.
Sıkça Sorulan Sorular
Q: Mühendislik ekiplerinde documentation rot nedir? A: Documentation rot, dahili belgeler doğruluğunun zamanla kademeli olarak bozulmasıdır. Yazıldığında doğru olan sayfalar, kod, süreçler ve ekip yapıları etraflarında değiştikçe yanıltıcı hale gelir. Belgelerin kendisi donmuş kalırken tanımladığı her şey gelişir.
Q: Sugarbug, documentation rot'u önlemeye yardımcı olur mu? A: Sugarbug, GitHub, Linear, Slack ve Notion gibi araçlara API aracılığıyla bağlanarak iş akışınız genelinde gerçekte ne olduğuna dair bir bilgi grafiği oluşturur. Elle bakılan wiki sayfalarına güvenmek yerine ekipler, gerçek faaliyetten gerçek bağlam ortaya çıkarabilir; bu da araçların kendisinden çekildiği için doğru kalır.
Q: Mühendislik belgeleri ne kadar hızlı güncel olmaktan çıkar? A: Deneyimimize ve mühendislik ekipleriyle yaptığımız görüşmelere göre, wiki sayfaları oluşturulduktan sonraki ilk birkaç hafta içinde gerçeklikten sapmaya başlar. Altı ay içinde pek çok sayfa, artık belgelenmiş biçimleriyle var olmayan süreçleri, uç noktaları veya sahiplik yapılarını tanımlar.
Q: Mühendislik belgelerini güncel tutmanın en iyi yolu nedir? A: En iyi çalışan yaklaşımlar şunlar: koda yakın belgeler (repodaki README'ler ve ADR'ler), otomatik eskime uyarıları ve elle bakılan sayfalara güvenmek yerine gerçek araçlarınızdan bağlam çeken canlı sorgulara geçmek. Süreç kontrol listeleri ("Her PR'da belgeleri güncelle") tutarlı biçimde başarısız oluyor, çünkü teşvik yapısı onları desteklemiyor.