--- title: 'Kod ile Birlikte Doküman' source: 'https://academia.sh/tr/kurslar/teknik-yazarlik/kod-ile-birlikte-dokuman' course: 'Teknik Yazarlık ve Dokümantasyon' language: tr updated: '2026-08-17T18:10:49+00:00' license: 'CC BY-SA 4.0' --- # Kod ile Birlikte Doküman Dokümanı kodla aynı depoda sürümlemek on iki sürümlük bayat borcunu 300/672'de bırakır, incelemeye de sokmak 43/672'ye indirir; incelemenin görmediği iki yüzeyde 15 iddia sessizce bayat kalır. Buraya kadarki her ölçüm dokümanı **yazıldığı andaki hâliyle** aldı. Dört türü, yüzey dağılımlarını, başlık düzenini ve örneklerin çalışırlığını hep tek bir anda, sıfırıncı sürümde ölçtük. O anda doküman bir metindir ve metnin bütün iddiaları doğrudur. Doküman o anda kalmaz. Anlattığı şey değişmeye devam eder ve doküman değişmezse **iddia (claim)** ile gerçeklik ayrışır. Bu dersin sorusu dokümanın nasıl yazıldığı değil, nerede durduğudur: doküman kodun yanında mı, ayrı bir yerde mi tutulur; değişiklikle aynı kayda mı girer, ayrı bir takvimde mi elden geçirilir. Üç işletim rejimi kuracağız ve aynı elli altı iddiayı on iki sürüm boyunca üçünde de izleyeceğiz. ## Üç İşletim Rejimi **Ayrı takvim.** Doküman kodun dışında yaşar; kendi deposu, kendi yayım düzeni vardır. Kimse onu bir değişiklikle birlikte açmaz. Belirli aralıklarla — kurgumuzda beş sürümde bir — biri oturur ve dokümanın tamamını gözden geçirir. O geçişte her iddia tazelenir, sonra doküman yeniden yalnız kalır. **Kodla birlikte sürümlenir.** Doküman kaynak ağacının içindedir ve değişikliğin kendisiyle aynı kayda girer. Bu **kod ile birlikte doküman (docs as code)** yaklaşımının çekirdeğidir: doküman ayrı bir varlık değil, deponun bir dosyasıdır. Yazan, kodu değiştirdiği kaydın içinde dokümana da dokunabilir. Dokunmak zorunda değildir. **Kodla birlikte sürümlenir ve incelemeye girer.** Değişiklik başkası tarafından okunur ve okuyan dokümanı da görür. Doküman satırları kod satırlarıyla aynı ekranda durduğu için "bu alanı yeniden adlandırdın, referansta eski adı duruyor" cümlesi kurulabilir hâle gelir. Üç rejim aynı yazma çabasını harcar. Aralarındaki fark **dokümanın ne zaman bakıldığıdır**, ne kadar iyi yazıldığı değil. Üçüncü rejimin iki koşulu vardır ve ikisi de yapısaldır. Birincisi, doküman dosyasının değişikliğin **içinde** bulunması: ayrı bir kayda alınan doküman düzeltmesi, düzelttiği kod değişikliğiyle aynı ekranda görünmez. İkincisi, eksik doküman güncellemesinin inceleyen tarafından bir **kusur sınıfı** sayılması: aynı listeye bakan iki kişiden biri dokunulmamış dosyayı bir eksiklik olarak okur, öbürü okumaz. Ölçüm ikinci koşulun sağlandığını varsayar; sağlanmadığında üçüncü rejim ikinciye çöker ve tablodaki fark ortadan kalkar. ## İncelemenin Gördüğü Yüzey İncelemenin kendi ekseni **Kod İnceleme ve Ekip Süreci** kursunda kuruldu: inceleme yalnız baktığı eksende ve okuduğu öbek kadarında görür. Burada o tartışma tekrarlanmıyor. Bize gereken tek şey şu sınırdır: **inceleyen, değişikliğin içinde görüneni okur.** Bu sınır dört yüzeyi ikiye böler. **İmza** ve **akış** değişikliğin içinde görünür: bir alanın türü değiştiğinde ya da adımların sırası değiştiğinde bunu üreten satırlar kaydın içindedir, inceleyen ikisini de yan yana okur. **Ad** ve **kavram** görünmez: bir şeyin dışarıya verilen adı ürün tarafında değişir, bir gerekçe tartışmada değişir; ikisi de kaynak satırında bir iz bırakmayabilir. İnceleyen dokümanda eski adı okuduğunda onu yanlış sanmak için hiçbir nedeni yoktur. Değişikliğin içinde dokümanın nerede durduğu da böyle görünür: ```text # ornek degisiklik listesi , calistirilmamistir değişiklik: ölçüm arayüzüne birim alanı eklenir kaynak/olcum.py +14 -3 kaynak/olcum_dogrula.py +6 -0 dokuman/referans/olcum.md +9 -4 dokuman/ogretici/ilk-olcum.md 0 0 ``` Dördüncü satır bu dersin ilgilendiği satırdır. Referans güncellenmiş, öğretici hiç dokunulmamış. İnceleyen bu listeyi görür ve öğreticinin dokunulmamış olduğunu fark edebilir; ama fark etmesi için öğreticinin **hangi iddiasının** bu değişiklikten etkilendiğini bilmesi gerekir. Bildiği durum imza ve akış, bilemediği durum ad ve kavramdır. ## Dokümanın Sürümü Dokümanı kodun yanına koymanın incelemeden bağımsız ikinci bir sonucu vardır: doküman deponun sürümleme düzenine girer. Bir dalda yapılan doküman değişikliği o dala aittir; bir sürüm etiketi konduğunda o etiket dokümanı da işaret eder. **Sürüm Kontrolüne Giriş** kursunun kurduğu ölçüt burada doğrudan işler — kayıt nesne veritabanına yazılmışsa geri getirilebilir. Dokümanın üçüncü sürümdeki hâli, üçüncü sürüm etiketinden okunabilir. Ayrı takvimle işletilen doküman bu özelliği taşımaz. Onun tek bir hâli vardır: **şimdiki hâl**. Üçüncü sürümü kullanan bir okur, altıncı sürümü anlatan bir metni okur ve aradaki farkı ölçemez. Bu, ölçtüğümüz bayatlamadan farklı bir yanlışlık türüdür: iddia bugünün kodu için doğrudur, okurun elindeki kod için yanlıştır. Ölçümümüz bunu **saymaz**, çünkü kâhin her sürümü tek tek bilir; gerçek bir kurulumda okurun hangi sürümde olduğu bilinmez ve bu belirsizlik doküman tarafından kapatılamaz. Sürümleme kararının doğrudan bir bedeli de vardır. Doküman kodla aynı dalda ilerlerse, bir düzeltme yayımlanmış sürüme ancak o sürümün dalına taşınarak ulaşır; ayrı takvimde ise düzeltme herkese anında görünür. Kod ile birlikte doküman yaklaşımı **doğruluğu sürüme bağlar** ve bunun karşılığında yayım işini çoğaltır. Kurgumuz bu maliyeti ölçmez; ölçtüğü tek şey iddianın doğru kalıp kalmadığıdır. ## Ölçümün Varsayımları - **DI1** — Elli altı iddia, dört tür ve dört yüzey ortak kurgudan alınır. Kâhin kurgunun kendisidir: hangi iddianın hangi yüzeye bağlı olduğunu ve hangi sürümde bayatladığını biz yazdığımız için biliriz. - **DI2** — Yüzey sıklıkları değişmez: imza iki sürümde bir, akış üçte bir, ad beşte bir, kavram on ikide bir değişir. Bir iddia bağlandığı yüzey değiştiği anda **bayatlar (staleness)**. - **DI3** — Elli altı iddianın on yedisi çalıştırılabilir örneğe gömülüdür. Gömülü bir iddia bayatlayınca ses çıkarır: örnek çalışmaz. Gömülü olmayan bir iddia bayatlayınca hiçbir şey olmaz; bu **sessiz bayatlamadır (silent staleness)**. - **DI4** — Ayrı takvim rejiminde doküman beşinci ve onuncu sürümde elden geçirilir ve o geçişte **her** iddia tazelenir. Ara sürümlerde kimse dokümana bakmaz. - **DI5** — Kodla birlikte sürümlenen rejimde yalnız gömülü iddialar onarılır: örnek çalışmadığı için bayatlama kendini duyurur ve aynı kayıtta düzeltilir. - **DI6** — İncelemeli rejimde gömülü iddialara ek olarak **imza ve akış** yüzeyine bağlı iddialar da onarılır; **ad ve kavram** yüzeyindekiler onarılmaz, çünkü değişikliğin içinde görünmezler. - **DI7** — Ölçünün birimi **bayat sürüm-iddia** sayısıdır: her sürümün sonunda bayat duran iddialar sayılır ve on iki sürüm boyunca toplanır. Üst sınır elli altı çarpı on iki, yani 672'dir. - **DI8** — Onarım, iddianın bayatladığı sürümün içinde olur. Rejimler arasındaki fark onarımın hızı değil, **hangi iddiaya hiç dokunulmadığıdır**. ## Ölçüm ```python """Dokumanin incelemeye girmesinin bayatlamaya etkisi. Bolum 1 - uc isletim rejimi, on iki surum boyunca bayat kalinan surum sayisi. Bolum 2 - yuzeylerin gomululuk ve incelemede gorunurluk dagilimi. """ TURLER = { "öğretici": {"akis": 9, "imza": 3, "ad": 2, "kavram": 1}, "nasıl yapılır": {"akis": 6, "imza": 5, "ad": 2, "kavram": 1}, "açıklama": {"akis": 1, "imza": 1, "ad": 1, "kavram": 9}, "referans": {"akis": 0, "imza": 13, "ad": 2, "kavram": 0}, } SIKLIK = {"imza": 2, "akis": 3, "ad": 5, "kavram": 12} ORNEKLI = {"öğretici": 0.60, "nasıl yapılır": 0.70, "açıklama": 0.10, "referans": 0.00} GORULEN = ("imza", "akis") # kod incelemesinin fark ettigi yuzeyler ELDEN_GECIRME = (5, 10) # ayri takvimde dokumanin gozden gecirildigi surum SON = 12 def iddialar(): liste, no = [], 0 for tur, dagilim in TURLER.items(): hedef = 0 for yuzey, adet in dagilim.items(): for _ in range(adet): no += 1 hedef += ORNEKLI[tur] gomulu = hedef >= 1 and yuzey != "kavram" if gomulu: hedef -= 1 liste.append({"no": no, "tur": tur, "yuzey": yuzey, "gomulu": gomulu}) return liste def degisen(surum): return {y for y, s in SIKLIK.items() if surum % s == 0} def onarir(rejim, iddia, surum): if rejim == "ayrı takvim": return surum in ELDEN_GECIRME if rejim == "birlikte sürümlenir": return iddia["gomulu"] return iddia["gomulu"] or iddia["yuzey"] in GORULEN REJIMLER = ("ayrı takvim", "birlikte sürümlenir", "birlikte + inceleme") def kosum(rejim, liste): dogru = {i["no"]: True for i in liste} borc = 0 for surum in range(1, SON + 1): d = degisen(surum) for i in liste: if i["yuzey"] in d: dogru[i["no"]] = False if not dogru[i["no"]] and onarir(rejim, i, surum): dogru[i["no"]] = True borc += sum(1 for i in liste if not dogru[i["no"]]) bayat = [i for i in liste if not dogru[i["no"]]] sessiz = [i for i in bayat if not i["gomulu"]] return borc, len(liste) - len(bayat), len(bayat), len(sessiz) L = iddialar() print(f"iddia {len(L)}, örneğe gömülü {sum(1 for i in L if i['gomulu'])}, " f"incelemenin gördüğü yüzey {sum(1 for i in L if i['yuzey'] in GORULEN)}") print() print(f"{'rejim':>20s} {'bayat sürüm-iddia':>18s} {'doğru':>6s} {'bayat':>6s} " f"{'sessiz':>7s}") for rejim in REJIMLER: borc, dogru, bayat, sessiz = kosum(rejim, L) print(f"{rejim:>20s} {f'{borc}/{len(L) * SON}':>18s} {dogru:6d} {bayat:6d} " f"{sessiz:7d}") print() print(f"{'yüzey':>7s} {'iddia':>6s} {'gömülü':>7s} {'incelemede görünür':>19s}") for y in SIKLIK: g = [i for i in L if i["yuzey"] == y] print(f"{y:>7s} {len(g):6d} {sum(1 for i in g if i['gomulu']):7d} " f"{'evet' if y in GORULEN else 'hayır':>19s}") ``` ``` iddia 56, örneğe gömülü 17, incelemenin gördüğü yüzey 38 rejim bayat sürüm-iddia doğru bayat sessiz ayrı takvim 299/672 7 49 35 birlikte sürümlenir 300/672 17 39 39 birlikte + inceleme 43/672 41 15 15 yüzey iddia gömülü incelemede görünür imza 22 5 evet akis 16 9 evet ad 7 3 hayır kavram 11 0 hayır ``` Sağdaki üç sütun on ikinci sürümün sonundaki durumu verir: kaç iddia doğru kalmış, kaçı bayat, bayatların kaçı sessiz. ## Aynı Borç, Farklı Dağılım İlk iki satırın toplamı neredeyse aynıdır: **299** ve **300**. Ayrı takvimle işletilen bir doküman ile kodla birlikte sürümlenen ama incelemeye girmeyen bir doküman, on iki sürüm boyunca hemen hemen aynı süreyi yanlış durumda geçirir. Kodun yanına taşımak tek başına bir kazanç üretmemiştir. Toplamlar eşit, dağılımlar tümüyle farklıdır. Ayrı takvimde hiçbir iddia kalıcı olarak bayat değildir — beşinci ve onuncu sürümdeki geçişler her şeyi sıfırlar — ama iki geçiş arasında **her tür iddia** bayat durur. On ikinci sürümde doğru kalan yalnız **7** iddia vardır ve bunlar son geçişten sonra yüzeyi hiç değişmemiş olanlardır: onuncu sürümde tazelenen ad iddiaları, çünkü ad beşte bir değişir ve bir sonraki değişimi on beşinci sürümdedir. Yedi sayısı ad yüzeyine bağlı iddia sayısının tamamıdır. Bu, ayrı takvim rejiminin borcunun nereden geldiğini de açıklar. **Elden geçirme aralığı en hızlı yüzeyin sıklığından büyükse, o yüzey iki geçiş arasında zaten bayatlar.** Beş sürümlük aralık, iki sürümde bir değişen imzaya karşı hiçbir şey yapmaz: yirmi iki imza iddiası her geçişten sonraki ikinci sürümde yeniden yanlışa düşer ve bir sonraki geçişe kadar öyle kalır. Aralığı kısaltmak borcu düşürür ama okuma işini doğrusal olarak büyütür; her geçiş elli altı iddianın elle doğrulanması demektir. Kodla birlikte sürümlenen rejimde tablo tersine döner: **17** iddia her zaman doğrudur ve **39** iddia on ikinci sürümde bayattır. On yedi sayısı tanıdıktır — tam olarak gömülü iddia sayısıdır. Otuz dokuz da tanıdıktır: bayatların **hepsi sessizdir**. Bu rejim gürültü çıkaranı hemen onarır, çıkarmayana hiç dokunmaz. Doküman kodun yanındadır, her değişiklikte gözün önünden geçer ve otuz dokuz iddia yıllarca yanlış kalır. **Kodla birlikte sürümlemek bir taşıma kararıdır, bir bakım kararı değildir.** Dosyanın yerini değiştirmek kimseye onu okuma yükümlülüğü getirmez. ## İncelemenin Kurtardığı ve Kurtaramadığı Üçüncü satır borcu **300**'den **43**'e indirir — yedi kat. Fark tek bir şeyden gelir: inceleyen, değişikliğin dokunduğu yüzeye bağlı doküman iddialarını da okur. Alt tablo kapsamı verir: incelemenin gördüğü iki yüzeye **38** iddia bağlıdır, yani elli altının üçte ikisinden fazlası. Geriye **15** iddia kalır ve tabloda hepsi sessizdir. Bunlar ad ve kavram yüzeyine bağlı, örneğe gömülü olmayan iddialardır: ad yüzeyinde **7 − 3 = 4**, kavram yüzeyinde **11**. Kavram sütunundaki gömülü sayısının sıfır olması kurgunun bir kuralıdır — bir gerekçe çalıştırılabilir bir örneğe gömülemez. Bu on beş iddia üç rejimin hiçbirinde bir uyarı üretmez. Örnek çalışır, inceleme geçer, kimse şikâyet etmez. On ikinci sürümde doküman **41** doğru iddia taşır ve okur için oldukça iyi görünür; taşıdığı **15** yanlış cümlenin hiçbiri kendini göstermez. Kursun merkezindeki sorun tam burada belirir ve sonraki iki ders onun üstüne kurulur: **bayatlamanın görünen bölümü ile var olan bölümü aynı şey değildir.** Rejimlerin bedeli de eşit değildir. Ayrı takvim iki tam gözden geçirme ister; elli altı iddianın hepsi iki kez elle doğrulanır. İncelemeli rejim hiç ek geçiş istemez, çünkü doğrulama zaten yapılan bir işin — değişikliğin okunmasının — içine yerleşir. Aradaki fark, doküman bakımının **ayrı bir iş** mi yoksa var olan bir işin **bir alanı** mı olduğu kararıdır. ## Ölçünün Söylemediği Üçüncü rejimin **43** sayısı bir alt sınırdır ve iyimserdir. Varsayım DI6 incelemenin gördüğü her iddiayı yakaladığını söyler; **Kod İnceleme ve Ekip Süreci** kursunun sonucu bunun doğru olmadığını gösterdi — inceleme baktığı eksende bile okuduğu öbek kadarını görür ve kaçırdığı kusur vardır. Doküman satırları o öbeğin en kolay atlanan bölümüdür, çünkü çalışmayı engellemezler. Gerçek bir kurulumda üçüncü satırın borcu **43**'ün üstünde, ikinci satırın **300**'ünün altında bir yerdedir. İki sayı bu iyimserlikten etkilenmez. Ad ve kavram yüzeyindeki **15** iddia, inceleme ne kadar dikkatli olursa olsun bu rejimde yakalanamaz: değişikliğin içinde görünmezler, dolayısıyla bakacak bir yer yoktur. Gömülü **17** iddia da tersinden aynı ölçüde kesindir: bunlar incelemeye hiç gerek duymaz, çünkü örnek çalışmadığında kendini söyler. Rejim seçimi yalnız aradaki **24** iddianın kaderini değiştirir. ## Özet - Doküman üç rejimde işletilebilir: ayrı takvimde gözden geçirilerek, kodla birlikte sürümlenerek, ya da kodla birlikte sürümlenip incelemeye sokularak. - Ayrı takvim **299/672**, kodla birlikte sürümleme **300/672** bayat sürüm-iddia üretir; ikisi eşit borç, tümüyle farklı dağılımdır. - Kodla birlikte sürümleme on ikinci sürümde **17** doğru iddia bırakır ve bayat kalan **39** iddianın **39**'u sessizdir; taşımak tek başına bakım değildir. - İnceleme borcu **43/672**'ye indirir ve doğru iddiayı **41**'e çıkarır, çünkü imza ile akış yüzeyindeki **38** iddiayı görür. - Geriye kalan **15** iddia ad ve kavram yüzeyindedir, incelemede görünmez ve hepsi sessizdir; bu sayı sonraki derslerin başlangıç noktasıdır. ## Sonraki Adım İnceleme, iddiayı **okuyan bir insan** olduğu için çalışır ve okuyan insan pahalıdır. Yüzeylerden biri için daha ucuz bir yol vardır: iddiayı elle yazmak yerine bağlandığı kaynaktan **üretmek**. Üretilen bir iddia kaynağıyla birlikte değişir ve bayatlaması düşünülemez hâle gelir. Sonraki ders üretim yaklaşımlarını sınıf adlarıyla ayırır ve üretimin hangi yüzeyi gerçekten kurtardığını, hangi iki yüzeyi hiç kurtarmadığını ölçer.