--- title: 'Depo Belgeleri' source: 'https://academia.sh/tr/kurslar/teknik-yazarlik/depo-belgeleri' course: 'Teknik Yazarlık ve Dokümantasyon' language: tr updated: '2026-08-17T18:10:49+00:00' license: 'CC BY-SA 4.0' --- # Depo Belgeleri Tanıtım dosyası, katkı rehberi ve mimari karar kaydı aynı sürümde başlar ve ayrı hızda çöker: üçü de ilk iddiasını ikinci sürümde kaybeder, ama ilk ikisi üçüncü sürümde yarılanırken karar kaydı on ikinci sürümde yarılanır ve on iki bayat iddiasının onunun onu sessizdir. Önceki iki ders dört türü ürünün çevresinde ölçtü: öğretici, nasıl yapılır, açıklama ve referans, hepsi ürünün **ne yaptığını** anlatan metinlerdi. Deponun içinde bunlardan başka belgeler de durur ve okurları ürünün okuru değildir. Depoya ilk kez bakan biri ürünü değil **bu deponun ne olduğunu** sorar; katkı vermek isteyen kişi ürünü değil **buranın düzenini** sorar; bir kararın gerekçesini arayan kişi ise ne ürünü ne düzeni, **geçmişte verilmiş bir yargıyı** sorar. Bu ders üç depo belgesini aynı ölçüye sokar: tanıtım dosyası, katkı rehberi ve mimari karar kaydı. Soru yine aynı — her belge hangi yüzeye bağlanıyor ve ne kadar dayanıyor — ama bu kez yanıt bakım önceliğine dönüşecek, çünkü üç belge aynı ilgiyi hak etmiyor. ## Üç Belge, Üç Okur Rolü **Tanıtım dosyası** deponun kapısıdır ve en geniş okur kümesine bakar. Yanıtladığı sorular sırayla şunlardır: bu ne, kime yarar, nasıl kurulur, ilk çıktı nasıl alınır, ayrıntı nerede. Beşinci soru önemlidir: tanıtım dosyasının işi anlatmak değil, **yönlendirmektir**. İçine öğretici de referans da sığmaz; sığdırıldığında bir önceki dersin ölçtüğü karışım bedeli doğar. Bu, depo belgelerinin en sık görülen bozulma biçimidir: tanıtım dosyası zamanla dokümantasyonun tamamına dönüşür, çünkü her yeni bilgiyi oraya eklemek en kısa yoldur. Sonuç, tek bir dosyada toplanmış ve ayrı hızlarda çürüyen bir iddia yığınıdır; hangi bölümün ne zaman yanlışlandığı artık okunamaz. **Katkı rehberi** dar bir okura bakar: koda dokunacak kişi. Yanıtladığı sorular geliştirme ortamının nasıl kurulacağı, testlerin nasıl çalıştırılacağı, dalın nasıl adlandırılacağı ve gönderilen işin nasıl karşılanacağıdır. Yazılı bir beklentinin **inceleme turlarını** nasıl kısalttığı **Kod İnceleme ve Ekip Süreci** kursunda ölçüldü ve burada tekrarlanmaz; bu derste katkı rehberi bir süreç aracı olarak değil, **bakımı gereken bir metin** olarak sayılır. **Mimari karar kaydı** en dar okura bakar ve tek bir soruya yanıt verir: bu neden böyle kararlaştırıldı? Kaydın yapısı — bağlam, karar, sonuçlar — ve mimari kararın nasıl belgeleneceği **Mimari Karar ve Dokümantasyon** kursunun konusudur ve burada tekrarlanmaz. Bu derste karar kaydı yalnız **hangi yüzeylere bağlandığıyla** ve ömrüyle ölçülür. ```text # kurgu deponun üç belgesinin iskeleti # örnek metin, çalıştırılmamıştır tanıtım dosyası Ölçüm İstasyonu nedir (kavram) Kurulum, ilk çalıştırma (akış) `istasyon baslat` seçenekleri (imza) Paket adı, dizin adları, bağlantılar (ad) katkı rehberi Neden bu düzen (kavram) Ortam kurma, test, gönderme adımları (akış) Test komutunun seçenekleri (imza) Dal adlandırma düzeni, etiket adları (ad) mimari karar kaydı Bağlam, karar, sonuçlar (kavram) Kararın bağladığı arayüz (imza) Bileşen adları (ad) ``` ## Neye Bağlandıkları İskelet üç belgenin karışımını doğrudan gösteriyor ve üçü birbirine benzemiyor. Tanıtım dosyası **dört yüzeyin dördüne birden** bağlanır. İçinde bir kurulum akışı, bir komut imzası, bir ürün adı ve bir gerekçe cümlesi bir arada durur. Bu, tanıtım dosyasını deponun en karma belgesi yapar; bakımı da bu yüzden en zordur, çünkü onu bozan olayların sayısı en fazladır. Katkı rehberi **akış ağırlıklıdır**: yazdığı şeyin çoğu bir sıradır. Adım anlatan her metin gibi, adımların kendisi değiştiğinde çöker. İkinci ağırlığı **addır** — dal adlandırma düzeni, etiket adları, dizin adları. Ad yüzeyi yavaş değişir ama değiştiğinde katkı rehberinin söylediği hiçbir şey hata vermez; yeni gelen kişi yanlış adlandırılmış bir dal açar ve bunu ancak biri söylerse öğrenir. Mimari karar kaydı neredeyse tümüyle **kavrama** bağlıdır. Bir kararın bağlamı ve sonucu, kod değiştiği için değişmez; ancak kararın kendisi yeniden ele alındığında değişir. Karşılığında karar kaydında **çalıştırılabilir hiçbir şey yoktur**: bir karar kaydı çalışmaz, dolayısıyla yanlışlandığında ses de çıkarmaz. ## Yönlendirmenin Ucuzluğu Tanıtım dosyasının beşinci sorusu — ayrıntı nerede — ilk dördü kadar masum değildir, çünkü yanıtı yazarın elindedir. Aynı bilgi iki biçimde konabilir: **anlatılarak** ya da **işaret edilerek**. Kurulum bölümü örnek olsun. Bütün seçenekleri tanıtım dosyasına dökmek, oraya bir yığın imza iddiası taşımak demektir; imza iki sürümde bir değişir. Aynı bölüm "seçeneklerin tümü referansta" diyerek tek bir işaretle geçilirse, taşınan şey bir **ad** iddiasına iner ve ad beş sürümde bir değişir — imzadan iki buçuk kat yavaş. Bilgi kaybolmaz, yalnız bir kez yazılır ve tanıtım dosyası ona bağlanır. Bunun bedeli de var: bağlantı hedefleri de bayatlar ve bir bağlantı koptuğunda okur hiçbir şey bulamaz. Ama iki kusur eşit değildir. Kopmuş bir bağlantı okurun **fark ettiği** bir kusurdur; yanlış yazılmış bir seçenek listesi okurun fark etmediği bir kusurdur. Tanıtım dosyasını yönlendirici yazmak, sessiz kusuru gürültülü kusura çevirir — kursun boyunca aynı takas birkaç kez daha karşımıza çıkacak. ## Aşılmış Kayıt Mimari karar kaydının ölçümde görünmeyen bir özelliği var. Öteki iki belge yanlışlandığında **düzeltilir**; karar kaydı yanlışlandığında düzeltilmez, **aşılır**. Kaydın kendisi olduğu gibi durur ve yeni bir kayıt onu geçersiz ilan eder. Bu, ölçüyü ortadan kaldırmaz ama sonucunu değiştirir. Bir kaydın kavram iddiaları bugünkü sistem için yanlışsa o kayıt bayattır — tablo bunu on ikinci sürümde **0/10** ile söylüyor. Ama kayıt tarih olarak okunuyorsa, iddiaları **verildikleri andaki** sistem için hâlâ doğrudur. Farkı tek bir alan taşır: kaydın durumu. Durum yazılmışsa okur baktığı metnin bugünü mü yoksa geçmişi mi anlattığını bilir; yazılmamışsa on yıllık bir gerekçeyi güncel sanarak okur. Bu, kursun boyunca görülen tek düzeltme biçimidir ki metni değiştirmez: **sessiz bayatlamayı susturmanın bir yolu, iddiayı düzeltmek yerine kapsamını yazmaktır.** Bir cümlenin hangi sürüm için doğru olduğunu söylemek, onu yanlışlıktan çıkarıp tarihe taşır. Ölçümün varsayımları: - **DT18** — Kurgu depoda üç belge vardır: tanıtım dosyası, katkı rehberi ve mimari karar kaydı. Depoda bulunabilecek başka belgeler bu ölçümün dışındadır. - **DT19** — Yüzeyler ve sıklıkları önceki derslerdekiyle aynıdır: imza **2**, akış **3**, ad **5**, kavram **12** sürümde bir. Bu dört sayı değiştirilmez. - **DT20** — Belgelerin yüzey karışımı yazım biçiminden gelir ve iskelette gösterildiği gibidir; karışım ölçüm boyunca sabit tutulur. - **DT21** — Tanıtım dosyası **12**, katkı rehberi **12**, mimari karar kaydı **10** iddia taşır. İlk iki belgenin eşit iddia taşıması kasıtlıdır: fark uzunluktan gelmesin. - **DT22** — Çalıştırılabilir örneğe gömülü iddia oranı tanıtım dosyasında **0,50**, katkı rehberinde **0,40**, mimari karar kaydında **0,00**'dır. Kavrama bağlı iddia gömülemez. - **DT23** — Bir iddia, bağlandığı yüzey ölçülen sürüme kadar en az bir kez değiştiyse bayattır ve kimse düzeltmez. - **DT24** — **İlk kayıp sürümü**, belgenin ilk bayat iddiasını verdiği sürümdür. **Yarılanma sürümü**, doğru kalan iddia payının **0,5**'in altına indiği ilk sürümdür. - **DT25** — Ölçüm **0, 2, 3, 5, 6 ve 12**'nci sürümleri kurar; bu sürümler yüzey sıklıklarının eşiklerine denk gelsin diye seçilmiştir. - **DT26** — Kümenin çözünürlüğü belge başına **1/12**, **1/12** ve **1/10**'dur; tek iddialık farkların altı bu kümeyle savunulamaz. ## Ölçüm ```python """Depo belgeleri: her belgenin bagli oldugu yuzey karisimi ve omru. Bolum 1 - uc belgenin yuzey karisimi ve gomulu iddia sayisi. Bolum 2 - surum boyunca dogru/bayat/sessiz, ilk kayip ve yarilanma surumu. """ SIKLIK = {"imza": 2, "akis": 3, "ad": 5, "kavram": 12} SURUMLER = (0, 2, 3, 5, 6, 12) # Uc depo belgesi: okuma sirasina gore yuzey karisimi. BELGELER = { "tanıtım dosyası": {"kavram": 2, "akis": 4, "imza": 3, "ad": 3}, "katkı rehberi": {"kavram": 1, "akis": 6, "imza": 2, "ad": 3}, "mimari karar kaydı": {"kavram": 7, "akis": 0, "imza": 1, "ad": 2}, } # Calistirilabilir ornege gomulu iddia orani. ORNEKLI = {"tanıtım dosyası": 0.50, "katkı rehberi": 0.40, "mimari karar kaydı": 0.00} def iddialar(): liste, no = [], 0 for belge, dagilim in BELGELER.items(): gomulu_hedef = 0 for yuzey, adet in dagilim.items(): for _ in range(adet): no += 1 gomulu_hedef += ORNEKLI[belge] gomulu = gomulu_hedef >= 1 and yuzey != "kavram" if gomulu: gomulu_hedef -= 1 liste.append({"no": no, "belge": belge, "yuzey": yuzey, "gomulu": gomulu}) return liste def bayat_mi(i, surum): return surum // SIKLIK[i["yuzey"]] >= 1 def olc(belge, surum, liste): grup = [i for i in liste if i["belge"] == belge] bayat = [i for i in grup if bayat_mi(i, surum)] sessiz = [i for i in bayat if not i["gomulu"]] return len(grup), len(grup) - len(bayat), len(bayat), len(sessiz) L = iddialar() print(f"belge {len(BELGELER)} | iddia {len(L)} | " f"örneğe gömülü {sum(i['gomulu'] for i in L)}") print() print(f"{'belge':<20s} {'iddia':>5s} {'kavram':>6s} {'akış':>5s} {'imza':>5s} " f"{'ad':>4s} {'gömülü':>6s}") for b in BELGELER: g = [i for i in L if i["belge"] == b] print(f"{b:<20s} {len(g):5d} " + " ".join(f"{sum(1 for i in g if i['yuzey'] == y):>{w}d}" for y, w in zip(("kavram", "akis", "imza", "ad"), (6, 5, 5, 4))) + f" {sum(i['gomulu'] for i in g):6d}") print() print(f"{'sürüm':>5s} " + " ".join(f"{b:>20s}" for b in BELGELER)) print(f"{'':5s} " + " ".join(f"{'doğru/bayat/sessiz':>20s}" for _ in BELGELER)) for s in SURUMLER: print(f"{s:5d} " + " ".join( f"{'{}/{}/{}'.format(*olc(b, s, L)[1:]):>20s}" for b in BELGELER)) print() print(f"{'belge':<20s} {'ilk kayıp':>9s} {'yarılanma':>9s} " f"{'12. sürümde doğru':>17s} {'sessiz':>6s}") for b in BELGELER: toplam = olc(b, 0, L)[0] ilk = next(s for s in range(1, 13) if olc(b, s, L)[2] > 0) yari = next((s for s in range(1, 13) if olc(b, s, L)[1] / toplam < 0.5), 0) _, dogru, _, sessiz = olc(b, 12, L) print(f"{b:<20s} {ilk:9d} {yari:9d} {f'{dogru}/{toplam}':>17s} " f"{sessiz:6d}") ``` ``` belge 3 | iddia 34 | örneğe gömülü 10 belge iddia kavram akış imza ad gömülü tanıtım dosyası 12 2 4 3 3 6 katkı rehberi 12 1 6 2 3 4 mimari karar kaydı 10 7 0 1 2 0 sürüm tanıtım dosyası katkı rehberi mimari karar kaydı doğru/bayat/sessiz doğru/bayat/sessiz doğru/bayat/sessiz 0 12/0/0 12/0/0 10/0/0 2 9/3/2 10/2/1 9/1/1 3 5/7/3 4/8/5 9/1/1 5 2/10/4 1/11/7 7/3/3 6 2/10/4 1/11/7 7/3/3 12 0/12/6 0/12/8 0/10/10 belge ilk kayıp yarılanma 12. sürümde doğru sessiz tanıtım dosyası 2 3 0/12 6 katkı rehberi 2 3 0/12 8 mimari karar kaydı 2 12 0/10 10 ``` ## Ömürlerin Okunması Alt tablonun ilk sütunu bir tuzağı kapatıyor: **ilk kayıp sürümü üç belgede de 2.** Üçünün de içinde en az bir imza iddiası var, dolayısıyla üçü de ilk kaybını aynı anda veriyor. Bir belgenin "eskimeye başladığı" an hiçbir şey ayırt etmez; her belge aynı anda eskimeye başlar. Ayırt eden şey **eğimdir**. Yarılanma sürümü tanıtım dosyasında **3**, katkı rehberinde **3**, mimari karar kaydında **12**. İlk iki belge üç sürüm içinde yarısını kaybederken karar kaydı aynı noktada **9/10** ile duruyor. Aradaki dört kat, yazım kalitesinden değil, karışımdan geliyor: karar kaydının **7** iddiası kavrama bağlı ve kavram on iki sürümde bir değişiyor. Beşinci sürüm satırı tabloyu en iyi özetleyen satır. Orada tanıtım dosyası **2/10/4**, katkı rehberi **1/11/7**, karar kaydı **7/3/3** veriyor. Aynı depoda, aynı gün yazılmış üç belge; beş sürüm sonra birinin onda yedisi ayakta, ötekilerin on ikide biri. Bakım bütçesi eşit dağıtılırsa üçte ikisi boşa gider — **karar kaydına ayrılan bakım, tanıtım dosyasına ayrılana göre dört kat daha az iş görür.** Sessiz sütunu ise ödünleşmeyi tersine çeviriyor. On ikinci sürümde üç belgenin üçü de tümüyle bayat; ama tanıtım dosyasının **12** bayat iddiasının **6**'sı, katkı rehberinin **12**'sinin **8**'i, karar kaydının **10**'unun **10**'u sessiz. En uzun yaşayan belge, bozulduğunda en az duyulan belgedir. Tanıtım dosyasının kurulum bölümü kırıldığında bunu her yeni okur anında görür; karar kaydının artık geçersiz olduğunu kimse görmez, çünkü karar kaydı çalıştırılmaz — ve o kayda dayanarak yeni bir karar verilir. Üçüncü sürüm satırı ayrıca katkı rehberinin özel durumunu veriyor: orada tanıtım dosyası **5/7/3**, katkı rehberi **4/8/5**. Akış yüzeyi tek bir kez değişti ve rehberin altı iddiasını birden aldı; rehber, tanıtım dosyasından **daha hızlı** çöktü. Bunun sıkıntısı okurunun kim olduğundan geliyor. Katkı rehberini okuyan kişi tanım gereği depoya yeni gelendir; bir adımın artık geçerli olmadığını anlayacak bilgiye sahip değildir ve yanlış adımı kendi hatası sanar. Deponun en yanlışlanabilir metni, yanlışı en az fark edebilecek okura veriliyor. Buradan iki ayrı bakım kuralı çıkıyor. Tanıtım dosyası ve katkı rehberi **sık ama ucuz** bakım ister: gömülü örnekleri çalıştıran bir kontrol, tanıtım dosyasında altı, katkı rehberinde dört iddiayı kendiliğinden yakalar. Mimari karar kaydı **seyrek ama pahalı** bakım ister: onu ancak bir insan, kararın bağlamına dönerek doğrulayabilir. İki belgeyi aynı takvimle denetlemek her ikisini de yanlış yerde denetlemek olur. ## Özet - Depo belgelerinin okuru ürünün okuru değildir: tanıtım dosyası depoya ilk bakanı, katkı rehberi koda dokunacak olanı, mimari karar kaydı gerekçe arayanı karşılar. - Tanıtım dosyası dört yüzeyin dördüne birden bağlanır (**2/4/3/3**), katkı rehberi akış ve ad ağırlıklıdır (**1/6/2/3**), mimari karar kaydı kavram ağırlıklıdır (**7/0/1/2**). - **İlk kayıp sürümü üçünde de 2**'dir ve hiçbir şey ayırt etmez; ayırt eden **yarılanma sürümüdür**: tanıtım dosyası **3**, katkı rehberi **3**, karar kaydı **12**. - Beşinci sürümde karar kaydı **7/3/3** ile ayakta, tanıtım dosyası **2/10/4**, katkı rehberi **1/11/7**; eşit dağıtılan bakım bütçesi bu yüzden yanlış yere gider. - En uzun yaşayan belge en sessiz bozulandır: on ikinci sürümde karar kaydının **10** bayat iddiasının **10**'u sessiz, tanıtım dosyasının **12**'sinin **6**'sı. - Anlatmak yerine işaret etmek iddiayı imzadan ada taşır ve ömrünü uzatır; karar kaydında ise durumu yazmak, bayat bir cümleyi yanlışlıktan çıkarıp tarihe taşır. ## Sonraki Adım Bu derste ölçülen üç belgenin hiçbirinde imza payı yarıyı geçmiyordu. Deponun en kalabalık imza kümesi başka yerde duruyor: arayüz referansında. İkinci ders onu **2/15** ile bırakmıştı ve bunun nedeni yazarın özensizliği değil, on beş iddianın on üçünün en hızlı yüzeye asılı olmasıydı. Sonraki ders bu türü kendi düzeniyle ele alır — uç nokta, parametre ve hata nasıl belgelenir — ve tek bir soruyu ölçer: bu iddialar elle yazılmak zorunda mı, yazılmazsa ne kadarı kurtulur ve geriye tam olarak ne kalır?