--- title: 'Teknik Yazarlık ve Dokümantasyon' source: 'https://academia.sh/tr/kurslar/teknik-yazarlik' language: tr updated: '2026-08-17T04:42:53+00:00' license: 'CC BY-SA 4.0' lessons: 15 outcomes: - 'Doküman türlerini okur kitleye ve amaca göre ayırır' - 'API referansı ve öğretici metni farklı yapılarla yazar' - 'Dokümanı kod ile birlikte sürümleyip güncel tutar' --- # Teknik Yazarlık ve Dokümantasyon Bir dokümanın değeri uzunluğu değil hâlâ doğru olan iddia sayısıdır; kurs dört doküman türünü bayatlama hızı, sessiz bayatlama oranı ve okurun sorusunu karşılayıp karşılamadığı üzerinden ölçer. ## Doküman Türleri Ürün, geliştirici ve destek içeriğinin ayrımı; öğretici, nasıl yapılır, açıklama ve referansın ayrı işlevleri; depo belgeleri; uç nokta ve hata belgeleme düzeni; sürüm notunun okura anlamı; ve belirti-neden-çözüm yapısı. ### Teknik Yazarlığın Kapsamı Source: https://academia.sh/tr/kurslar/teknik-yazarlik/teknik-yazarligin-kapsami Bir dokümanın sayısı uzunluğu değil taşıdığı iddia sayısıdır: dört tür 56 iddia taşır, iddialar imza, akış, ad ve kavram yüzeylerine 22, 16, 7 ve 11 dağılır, 17'si çalıştırılabilir örneğe gömülüdür ve imza yüzeyinin tek bir değişimi 22 iddiayı düşürüp 17'sini sessizce düşürür. Önceki kurs bir incelemenin sayısını bakan kişi sayısıyla değil, bakılan eksen ve okunan öbek sayısıyla ölçtü ve kapanışında bir sınır çizdi: **inceleme yazılana bakar; yazılmayanı yazmak ayrı bir iştir.** Orada ölçülen şey kusurun bulunup bulunmadığıydı — değişiklik masadaydı, inceleyen ona bakıyordu ve ölçüm bir tek anda yapılıyordu. Doküman öyle çalışmaz. Bir doküman yazıldığı gün doğrudur; ilginç olan sonrasıdır. Bu kursun ölçtüğü şey **yazılanın hâlâ doğru olup olmadığı** ve yanlışlaştığında bunun **duyulup duyulmadığıdır.** Bu ders o ölçünün birimini kurar: dokümanın kaç cümlesi doğru ya da yanlış olabilir, o cümleler neye bağlıdır ve bağlandıkları şey değiştiğinde kim duyar. #### Üç İçerik Kümesi Teknik yazarlık tek bir iş değil; okuru ve tetikleyicisi ayrı üç kümedir. **Ürün içeriği** ürünü hiç kullanmamış birine ne olduğunu anlatır; tetikleyicisi bir karardır ve okuru henüz kullanıcı değildir. **Geliştirici içeriği** ürünü kullanacak ya da genişletecek kişiye çalışma biçimini anlatır; tetikleyicisi bir görevdir. **Destek içeriği** bir şey ters gittiğinde okunur; tetikleyicisi bir arızadır ve okuru elinde bir belirtiyle gelir. Üçü aynı ölçüyle ölçülmez. Ürün içeriğinin doğruluğu genelde bir konumlandırma sorusudur ve teknik bir kâhini yoktur. Bu kurs **geliştirici içeriğini** ölçer: doğru ya da yanlış olduğu söylenebilecek, karşılığı kodda duran cümlelerden kurulu metinleri. Destek içeriği ölçüye sonradan, kendi dersinde girer; ürün içeriği kursun dışında kalır. Geliştirici içeriği dört türe ayrılır ve dördü aynı okuru farklı anda karşılar. **Öğretici** hiç bilmeyeni bir kez sonuca götürür. **Nasıl yapılır** belirli bir görevi olan kişiyi o görevin adımlarına götürür. **Açıklama** neden öyle olduğunu anlatır. **Referans** tek tek alanların, seçeneklerin ve dönüş değerlerinin dökümüdür. Bu dört ad kurs boyunca sabittir. #### Dokümanın Sayısı Uzunluğu Değildir Bir dokümanı sayfa sayısıyla ölçmek işe yaramaz, çünkü uzunluk ne okurun sorusunu yanıtladığını söyler ne de metnin doğru olduğunu. Bu kursun birimi **iddiadır**: dokümanda geçen, doğru ya da yanlış olabilecek her cümle bir iddiadır. Cilalı bir paragraf sıfır iddia taşıyabilir; üç satırlık bir kurulum bölümü dört iddia taşıyabilir. Aşağıdaki parça kurgu bir üründen — "Ölçüm İstasyonu" adında, yalnız bu kurs için var olan bir ölçüm aracından — alınmıştır. ```text # kurgu ürünün tanıtım dosyasından bir parça # örnek metin, çalıştırılmamıştır ## Kurulum Paketi kurun ve `istasyon baslat` komutunu çalıştırın. Komut `--aralik` seçeneğini saniye cinsinden alır. Varsayılan profilin adı `yerel`. Aralık, ölçümün örnekleme penceresini belirler; pencere kısaldıkça ölçüm gürültüsü artar. ``` Dört cümle, dört iddia. Hepsi bugün doğru. Ama dördü **aynı şeye** bağlı değil ve bu ayrım kursun tamamını taşır. #### Ölçünün Yanlış Vekilleri İddia sayımına geçmeden önce, yerine sık kullanılan üç vekili elemek gerekir; üçü de kolay toplanır ve üçü de yanlış şeyi sayar. **Uzunluk.** Sayfa ya da kelime sayısı yazılan emeği ölçer, doğruluğu değil. İki bin kelimelik bir öğreticinin tamamı yanlış olabilir; on satırlık bir bölüm eksiksiz doğru olabilir. Uzunluk büyüdükçe iddia sayısı da büyür, yani uzun doküman **daha çok yanlışlanabilir** demektir — ters yönde bir gösterge. **Son güncelleme damgası.** Dokümanın üstündeki tarih, dokümana **dokunulduğunu** söyler; doğrulandığını söylemez. Bir yazım düzeltmesi damgayı tazeler ve altındaki kırk iddiayı olduğu gibi bırakır. Tersi de geçerlidir: bir yıl dokunulmamış bir açıklama, bağlandığı kavram değişmediyse hâlâ tamamen doğrudur. Damga, dokümanın yaşını ölçer; sorulan şey ise **bağlandığı yüzeyin** yaşıdır. **Kapsama oranı.** "Uç noktaların yüzde kaçı belgelenmiş" sorusu eksiği ölçer, yanlışı değil. Belgelenmemiş bir uç nokta okuru kaynağa yollar; **yanlış belgelenmiş** bir uç nokta okuru yanlış yere yollar ve gittiğini de söylemez. Kapsama oranı yükselirken doğruluk düşebilir, çünkü ikisi farklı şeyler sayar. Üç vekilin ortak kusuru şudur: hiçbiri dokümanın **neye bağlı olduğuna** bakmaz. Ölçü oraya bakmak zorundadır. #### İddia Neye Bağlanır Her iddia bir **yüzeye** bağlıdır: doğruluğunu borçlu olduğu şeye. **İmza**, arayüzün biçimidir — bir seçeneğin adı, bir alanın tipi, bir işlevin aldığı parametreler. `--aralik` seçeneğinin saniye alması bir imza iddiasıdır. **Akış**, adımların sırasıdır: önce kur, sonra çalıştır. **Ad**, bir şeyin adıdır; varsayılan profilin `yerel` diye anılması bir ad iddiasıdır. **Kavram**, neden öyle olduğudur; pencere kısaldıkça gürültünün artması kavram iddiasıdır. Yüzeyler aynı hızda değişmez ve bu kursun sabitidir: **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** — metin aynı kalır, karşılığı kayar. Buradan çıkan ilk sonuç şudur: bir cümlenin ömrünü yazarın özeni değil, cümlenin **neye bağlandığı** belirler. Aynı dikkatle yazılmış iki cümleden biri iki sürüm, öteki on iki sürüm yaşar. #### Ses Çıkaran ve Çıkarmayan İkinci bir ayrım daha var ve kursun kendi katkısı odur. İddiaların bir bölümü **çalıştırılabilir örneğe gömülüdür**: bir komut satırının, bir kod parçacığının içinde durur. Gömülü bir iddia bayatladığında örnek çalışmaz — biri onu çalıştırdığı anda **ses çıkarır**. Gömülü olmayan bir iddia bayatladığında hiçbir şey olmaz: metin aynı kalır, kimse fark etmez, okur yanlış cümleyi doğru sanarak okur. Buna **sessiz bayatlama** denir. Ses çıkarma yüzeye de bağlıdır. Kavram iddiası hiçbir örneğe gömülemez; "pencere kısaldıkça gürültü artar" cümlesi çalıştırılabilir bir şey değildir. İmza iddiası gömülebilir ama gömülmek zorunda değildir: bir tablo satırında duran alan tipi ile örnek çağrının içinde duran alan tipi aynı şeyi söyler, biri sessizdir, öteki değil. Sesi kimin duyduğu da belirlidir. **Yeni okur** örneği kopyalayıp çalıştırır; gömülü bir iddia bayatlamışsa hatayı ilk o alır ve çoğu zaman bunun dokümanın kusuru olduğunu bilmez, kendi kurulumundan şüphelenir. **Bakım yapan** ise dokümanı okur, çalıştırmaz; sessiz bir iddianın yanlış olduğunu ancak zaten bildiği bir konuda okursa fark eder — yani yalnız yardıma gereksinmediği yerde. Sessiz bayatlamanın kalıcı olmasının nedeni budur: onu görebilecek kişi oraya bakmaz, oraya bakan kişi göremez. Ölçümün varsayımları: - **DT1** — Kurgu ürünün dört dokümanı vardır ve türleri **öğretici, nasıl yapılır, açıklama, referans**'tır. Dört türün tanımı kurs boyunca değişmez. - **DT2** — Dördü birlikte **56** iddia taşır. İddia, dokümanda doğru ya da yanlış olabilecek tek bir cümledir; üslup, başlık ve bağlantı iddia sayılmaz. - **DT3** — Her iddia tam bir yüzeye bağlıdır: **imza**, **akış**, **ad** ya da **kavram**. Birden çok yüzeye bağlı cümle bu ölçümde iki iddiaya bölünmüş sayılır. - **DT4** — Yüzeylerin değişme sıklığı sabittir: imza **2**, akış **3**, ad **5**, kavram **12** sürümde bir. Bu dört sayı kursun hiçbir dersinde değiştirilmez. - **DT5** — Türlerin yüzey karışımı yazım biçiminden gelir: öğretici ve nasıl yapılır adım anlatır, bu yüzden akış ağırlıklıdır; referans alan döker, bu yüzden imza ağırlıklıdır; açıklama gerekçe kurar, bu yüzden kavram ağırlıklıdır. - **DT6** — Çalıştırılabilir örneğe gömülü iddia oranı türe göre değişir: öğretici **0,60**, nasıl yapılır **0,70**, açıklama **0,10**, referans **0,00**. Kavram yüzeyine bağlı hiçbir iddia gömülü olamaz. - **DT7** — Kâhin kurgunun kendisidir: hangi iddianın hangi yüzeye bağlı olduğunu ve ne zaman bayatlayacağını kurguyu biz yazdığımız için biliriz. Gerçek bir depoda bu bilgi yoktur ve kursun sonraki dersleri onu nasıl üreteceğini sorar. - **DT8** — Kümenin çözünürlüğü **1/56**'dır; tek bir iddia bu ölçümde ayırt edilebilen en küçük farktır. #### Ölçüm ```python """Dokumanin yazildigi andaki bilesimi: 56 iddia, dort tur, dort yuzey. Bolum 1 - tur basina iddia, yuzey karisimi ve ornege gomulu iddia. Bolum 2 - bir yuzeyin tek degisiminin dusurdugu iddia ve sessiz kalani. """ 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}, } YUZEYLER = ("imza", "akis", "ad", "kavram") # Calistirilabilir ornege gomulu iddia orani: bunlar bayatlayinca ses cikarir. ORNEKLI = {"öğretici": 0.60, "nasıl yapılır": 0.70, "açıklama": 0.10, "referans": 0.00} def iddialar(): """Her iddia: turu, bagladigi yuzey, ornege gomulu mu.""" liste, no = [], 0 for tur, dagilim in TURLER.items(): gomulu_hedef = 0 for yuzey, adet in dagilim.items(): for _ in range(adet): no += 1 gomulu_hedef += ORNEKLI[tur] gomulu = gomulu_hedef >= 1 and yuzey != "kavram" if gomulu: gomulu_hedef -= 1 liste.append({"no": no, "tur": tur, "yuzey": yuzey, "gomulu": gomulu}) return liste L = iddialar() print(f"iddia {len(L)} | tür {len(TURLER)} | yüzey {len(YUZEYLER)} | " f"örneğe gömülü {sum(i['gomulu'] for i in L)}") print() print(f"{'tür':<14s} {'iddia':>5s} {'imza':>5s} {'akış':>5s} {'ad':>4s} " f"{'kavram':>6s} {'gömülü':>6s} {'sessiz':>6s}") for tur in TURLER: g = [i for i in L if i["tur"] == tur] gom = sum(i["gomulu"] for i in g) print(f"{tur:<14s} {len(g):5d} " + " ".join(f"{sum(1 for i in g if i['yuzey'] == y):>{w}d}" for y, w in zip(YUZEYLER, (5, 5, 4, 6))) + f" {gom:6d} {len(g) - gom:6d}") print(f"{'toplam':<14s} {len(L):5d} " + " ".join(f"{sum(1 for i in L if i['yuzey'] == y):>{w}d}" for y, w in zip(YUZEYLER, (5, 5, 4, 6))) + f" {sum(i['gomulu'] for i in L):6d} " f"{sum(not i['gomulu'] for i in L):6d}") print() print("yazıldığı an (sürüm 0) — doğru/bayat/sessiz") print(" " + " | ".join(f"{t} {len([i for i in L if i['tur'] == t])}/0/0" for t in TURLER)) print() print(f"{'değişen yüzey':<14s} {'düşen iddia':>11s} {'pay':>6s} " f"{'ses çıkaran':>11s} {'sessiz':>6s} {'sessiz payı':>11s}") for y in YUZEYLER: d = [i for i in L if i["yuzey"] == y] sesli = sum(i["gomulu"] for i in d) print(f"{y:<14s} {len(d):11d} {len(d) / len(L):6.4f} {sesli:11d} " f"{len(d) - sesli:6d} {(len(d) - sesli) / len(d):11.4f}") ``` ``` iddia 56 | tür 4 | yüzey 4 | örneğe gömülü 17 tür iddia imza akış ad kavram gömülü sessiz öğretici 15 3 9 2 1 8 7 nasıl yapılır 14 5 6 2 1 9 5 açıklama 12 1 1 1 9 0 12 referans 15 13 0 2 0 0 15 toplam 56 22 16 7 11 17 39 yazıldığı an (sürüm 0) — doğru/bayat/sessiz öğretici 15/0/0 | nasıl yapılır 14/0/0 | açıklama 12/0/0 | referans 15/0/0 değişen yüzey düşen iddia pay ses çıkaran sessiz sessiz payı imza 22 0.3929 5 17 0.7727 akis 16 0.2857 9 7 0.4375 ad 7 0.1250 3 4 0.5714 kavram 11 0.1964 0 11 1.0000 ``` #### Bileşimin Okunması Üçüncü blok kursun başlangıç noktasını veriyor: yazıldığı gün dört dokümanın hepsi **kusursuz**. Elli altı iddianın elli altısı doğru, bayat **0**, sessiz **0**. Ölçü bu noktada hiçbir şey ayırt etmiyor — bu yüzden yazıldığı andaki kaliteyi ölçmek bir dokümanı ölçmez. Üst tablo asıl bilgiyi taşıyor. Öğretici ile referansın **ikisi de 15 iddia** taşıyor; eşit uzunlukta iki doküman gibi görünüyorlar. Bileşimleri ise birbirinin tersi: öğreticinin 15 iddiasının **9**'u akışa bağlı, referansın 15 iddiasının **13**'ü imzaya. Ve gömülülük sütunu ikisini büsbütün ayırıyor — öğreticide **8** iddia örneğe gömülü, referansta **0**. Referans, bayatladığında hiçbir ses çıkarmayan tek türdür ve bunu tür olduğu için değil, **hiç örnek taşımadığı için** yapar. Açıklamanın gömülü iddiası da **0**. Ama sebebi başka: iddialarının **9**'u kavrama bağlı ve kavram iddiası gömülemez. İki tür aynı sayıda sessiz iddia üretiyor, biri hiç örnek yazmadığı için, öteki yazamayacağı için. Bunun toplamdaki sonucu tek satırda okunuyor: **17** gömülü iddianın **17**'si öğretici ile nasıl yapılır türlerinde. Dört türlük bir doküman kümesinin ürettiği bütün ses **iki türden** geliyor; kalan iki tür, birlikte **27** iddia taşımasına karşın hiç ses çıkarmıyor. Bu, o iki türü kötü yapmaz — açıklamanın işi gerekçedir, referansın işi dökümdür — ama şunu söyler: **bir doküman kümesinin bakım uyarısı, kümenin tamamından değil, örnek taşıyan bölümünden gelir.** Örnek taşımayan bölüm ne kadar büyürse, küme o kadar sessizleşir. Alt tablo tek bir değişimin bedelini veriyor. **İmza yüzeyi bir kez değiştiğinde 22 iddia düşer** — kümenin **0,3929**'u, üçte birinden fazlası. Bunun yalnız **5**'i ses çıkarır; **17**'si sessizce düşer, yani imza değişiminin **0,7727**'si duyulmaz. İmza aynı zamanda **en hızlı değişen** yüzeydir: iki sürümde bir. En kalabalık ve en sessiz küme, en sık değişen yüzeye asılıdır. Karşılaştırma akış yüzeyinde tersine dönüyor: akışa **16** iddia bağlı, **9**'u ses çıkarıyor ve sessiz payı **0,4375**'e iniyor. Akış iddiaları adım anlatır, adımlar örneğe girer, örnek kırılır. Kavram yüzeyinde sessiz payı **1,0000** — on bir iddianın hiçbiri ses çıkarmaz — ama kavram on iki sürümde bir değişir, yani bu on bir iddia hem en uzun yaşayan hem de bayatladığında en görünmez olanlardır. Buradan kursun ölçü ekseni tam biçimini alıyor: bir dokümanın sayısı uzunluğu değil, **hâlâ doğru olan iddia sayısıdır** — ve bayatlayanların **kaçının sessiz** olduğudur. İki dokümanın hangisinin daha iyi bakıldığını yazım kalitesinden okuyamazsınız; bileşiminden okuyabilirsiniz. #### Özet - Teknik yazarlık ürün, geliştirici ve destek içeriği diye üç kümeye ayrılır; bu kurs doğru ya da yanlış olduğu söylenebilen **geliştirici içeriğini** ölçer. - Dokümanın birimi **iddiadır**: doğru ya da yanlış olabilecek tek cümle. Dört türün dokümanı birlikte **56** iddia taşır ve uzunluk bu sayıyı vermez. - Her iddia bir **yüzeye** bağlıdır — imza **22**, akış **16**, ad **7**, kavram **11** — ve yüzeyler farklı hızda değişir: **2**, **3**, **5** ve **12** sürümde bir. - **17** iddia çalıştırılabilir örneğe gömülüdür ve bayatladığında ses çıkarır; kalan **39** sessizce bayatlar. Referansın gömülü iddiası **0**, açıklamanınki de **0**'dır. - İmza yüzeyinin tek bir değişimi **22** iddiayı düşürür (**0,3929**) ve bunun **17**'si sessizdir (**0,7727**); aynı hesap akışta **16** iddia ve **0,4375** sessizlik verir. #### Sonraki Adım Bu ders dört türü yalnız adlandırdı ve bileşimlerini saydı; hangisinin ne kadar dayandığını ölçmedi. Sonraki ders saati işletiyor: aynı dört doküman iki sürüm sonra ne durumda? Elle yazılmış referansın on beş iddiasından kaçı ayakta kalır, açıklama on iki iddiasının kaçını korur ve iki tür arasındaki fark kaç kat çıkar? Aynı derste ikinci bir soru daha sorulacak: okur dokümana altı ayrı soruyla gelir; bu dört tür o soruların kaçını karşılar? ### Öğretici, Nasıl Yapılır, Açıklama ve Referans Source: https://academia.sh/tr/kurslar/teknik-yazarlik/ogretici-nasil-yapilir-aciklama-ve-referans Dört tür aynı konuyu ayrı işlevle yazar ve ayrı hızda bayatlar: tek bir imza değişimi ikinci sürümde referansın 15 iddiasından 13'ünü düşürüp geriye 2 bırakır, açıklama 12'nin 11'ini korur, ömür farkı 6,875 kat çıkar; altı okur sorusunun dördü bir türe düşer, ikisi hiçbirine. Önceki ders dört dokümanı yazıldıkları an saydı: **56** iddia, dört yüzey, **17** gömülü örnek — ve elli altı iddianın elli altısı doğru. O tabloda türler birbirinden yalnız bileşimleriyle ayrılıyordu, sonuçlarıyla değil, çünkü henüz hiçbir şey değişmemişti. Bu ders iki soruyu birden sorar. Birincisi işlevle ilgilidir: dört tür aynı konuyu neden ayrı ayrı yazar, aralarındaki fark nedir? İkincisi ömürle ilgilidir: saat iki sürüm işletildiğinde hangisinden ne kalır? İkinci sorunun yanıtı, birinci sorunun yanıtından **doğrudan** çıkacak. #### Dört Türün Ayrı İşlevi Okur dokümana rastgele gelmez; bir durumla gelir ve o durum hangi türe gideceğini belirler. **Öğretici** hiç bilmeyen okuru bir kez sonuca götürür. Sözü verilen şey öğrenmek değil, **bir sonuç almaktır**: sonunda okurun elinde çalışan bir şey olur. Bu yüzden öğretici tek yol gösterir, seçenek sunmaz ve okura doğrudan seslenen tek türdür. **Nasıl yapılır** okuru zaten bilen biri sayar; belirli bir görevi vardır ve ona en kısa yoldan ulaşmak ister. Öğreticiden farkı sonucu değil, **giriş noktasını** değiştirmesidir: okur baştan değil, ortadan girer. **Açıklama** hiçbir görevin ortasında değildir. Okuru bir şeyi yapmaya değil, **anlamaya** gelmiştir; sorusu "neden böyle" ve yanıtı bir gerekçedir. **Referans** ise okunmaz, bakılır. Okur ne aradığını bilir, tek bir alanın tipini ya da varsayılanını doğrulamak ister ve gerekçeye ayıracak vakti yoktur. Aşağıdaki parça kurgu "Ölçüm İstasyonu" ürününün dört dokümanının **aynı seçeneği** nasıl yazdığını gösteriyor. ```text # kurgu ürünün dört türü aynı seçeneği nasıl yazar # örnek metin, çalıştırılmamıştır öğretici İlk ölçümü almak için `istasyon baslat --aralik 5` komutunu çalıştırın. Beş saniyede bir satır düşer. nasıl yapılır Örnekleme sıklığını değiştirmek için `--aralik` seçeneğine saniye cinsinden bir tamsayı verin. açıklama Aralık, örnekleme penceresinin genişliğidir. Pencere kısaldıkça tek tek okumalardaki gürültü artar; uzadıkça ani değişimler ortalamanın içinde kaybolur. referans --aralik tip: tamsayı varsayılan: 60 alt sınır: 1 ``` Türleri asıl ayıran şey ne yazdıkları değil, **ne yazmadıklarıdır.** Öğretici gerekçe vermez — verirse okuru duraklatır ve sonuca ulaşmayı geciktirir. Nasıl yapılır metni baştan başlamaz; okurun kuruluma sahip olduğunu varsayar. Açıklama adım vermez; verdiği anda okurun izleyeceği bir yol doğar ve o yol bakımsız kalır. Referans öğretmez; bir alanın ne işe yaradığını anlatmaya kalkarsa aynı gerekçe iki yerde durur ve ikisi ayrı hızda bayatlar. Bu dört olumsuz kural, dört olumlu kuraldan daha çok iş görür. Dördü de doğru ve dördü de gerekli. Türleri karıştırmanın ilk bedeli okurun aradığını bulamamasıdır: gerekçe arayan okur öğreticiye düşerse yalnız adımları bulur; görev sahibi okur açıklamaya düşerse yirmi satır okuyup hiçbir komut bulamaz. Ama bu dersin ölçtüğü bedel o değil. Ölçülen şey, dört türün aynı olay karşısında **ne kaybettiğidir**. #### Aynı Olay, Dört Farklı Fatura Yukarıdaki parçada dört metnin kaç iddia taşıdığına değil, iddialarının **neye bağlandığına** bakın. Öğretici satırı bir sırayı anlatıyor — akış. Nasıl yapılır satırı hem sırayı hem seçeneğin biçimini taşıyor. Açıklama satırı bir gerekçe kuruyor — kavram. Referans satırının her hücresi arayüzün biçimidir: ad, tip, varsayılan, alt sınır. Referansın yazdığı **her şey** imzadır. Şimdi ürünün ikinci sürümü çıksın ve tek bir şey olsun: **imza yüzeyi bir kez değişsin.** Seçeneğin adı, tipi ya da varsayılanı kaysın. Kimse dokümana dokunmadı; dört metin de dünkü hâliyle duruyor. Bu tek olayın dört türe kestiği fatura aynı değildir ve ölçüm tam olarak bunu sayar. Ölçümün varsayımları: - **DT9** — Kurgu kümesi önceki dersteki kümedir: **56** iddia, dört tür ve dört yüzey. Tür tanımları ve yüzey sıklıkları değiştirilmez. - **DT10** — Sürüm sayacı yalnız yüzeyleri işletir. Bir yüzey, sıklığının katı olan her sürümde bir kez değişir; imza **2**, akış **3**, ad **5**, kavram **12** sürümde bir. - **DT11** — Bir iddia, bağlandığı yüzey ölçülen sürüme kadar **en az bir kez** değiştiyse bayattır. Bayatlama geri alınmaz: bu ölçümde kimse dokümanı düzeltmiyor. - **DT12** — Ölçüm **sürüm 0, 1 ve 2**'yi kurar. Sonraki sürümler bu derste kurulmaz ve sayıları buradan okunmaz. - **DT13** — Okurun altı sorusu vardır ve her soru tek bir türe düşer ya da hiçbirine düşmez. Soru kümesi kursun sabitidir; ders onu genişletmez. - **DT14** — Bir soru, yanıtını taşıyan tür **var ise** yanıtlanmış sayılır. Yanıtın hâlâ doğru olup olmadığı ayrı bir sütunda ölçülür; ikisi karıştırılmaz. - **DT15** — Yanıtın **güveni**, o türün ölçülen sürümde doğru kalan iddialarının payıdır. Bu bir olasılık değil, kümenin oranıdır. - **DT16** — İki tür tek sayfada birleştirilirse iddialar toplanır ve okur sayfanın tamamını tek bir metin olarak görür; sayfanın güveni birleşik kümenin doğru payıdır. - **DT17** — Kümenin çözünürlüğü **1/56**'dır; tek iddialık farklar anlamlıdır, ondan küçüğü bu kümeyle savunulamaz. #### Ölçüm ```python """Dort turun ayri isleviyle ayri omru: ikinci surumde ne kaldi. Bolum 1 - surum 0, 1 ve 2'de her turun dogru/bayat/sessiz uclusu. Bolum 2 - alti okur sorusu, yanitlayan tur ve yanitin ikinci surumdeki gucu. """ 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} # Okurun getirdigi soru -> yanitlayan tur; None ise hicbir tur yanitlamaz. SORULAR = { "nereden başlarım": "öğretici", "şunu nasıl yaparım": "nasıl yapılır", "bu neden böyle": "açıklama", "bu alanın tipi ne": "referans", "hangi sürümde değişti": None, "bu neden çalışmıyor": None, } def iddialar(): liste, no = [], 0 for tur, dagilim in TURLER.items(): gomulu_hedef = 0 for yuzey, adet in dagilim.items(): for _ in range(adet): no += 1 gomulu_hedef += ORNEKLI[tur] gomulu = gomulu_hedef >= 1 and yuzey != "kavram" if gomulu: gomulu_hedef -= 1 liste.append({"no": no, "tur": tur, "yuzey": yuzey, "gomulu": gomulu}) return liste def bayat_mi(i, surum): """Bagli oldugu yuzey bu surume kadar en az bir kez degistiyse bayattir.""" return surum // SIKLIK[i["yuzey"]] >= 1 def olc(surum, liste): d = {} for tur in TURLER: grup = [i for i in liste if i["tur"] == tur] bayat = [i for i in grup if bayat_mi(i, surum)] sessiz = [i for i in bayat if not i["gomulu"]] d[tur] = (len(grup), len(grup) - len(bayat), len(bayat), len(sessiz)) return d L = iddialar() print(f"iddia {len(L)} | tür {len(TURLER)}") print() print(f"{'sürüm':>5s} {'değişen yüzey':<14s} " + " ".join(f"{t:>15s}" for t in TURLER)) print(f"{'':5s} {'':14s} " + " ".join(f"{'doğru/bayat/sessiz':>15s}" for _ in TURLER)) for s in (0, 1, 2): degisen = [y for y in SIKLIK if s // SIKLIK[y] >= 1] or ["—"] d = olc(s, L) print(f"{s:5d} {', '.join(degisen):<14s} " + " ".join(f"{f'{d[t][1]}/{d[t][2]}/{d[t][3]}':>15s}" for t in TURLER)) print() d2 = olc(2, L) print(f"{'soru':<22s} {'yanıtlayan tür':<14s} {'sürüm 2':>8s} {'güven':>7s}") for soru, tur in SORULAR.items(): if tur is None: print(f"{soru:<22s} {'—':<14s} {'—':>8s} {'—':>7s}") else: _, dogru, _, _ = d2[tur] toplam = d2[tur][0] print(f"{soru:<22s} {tur:<14s} {f'{dogru}/{toplam}':>8s} " f"{dogru / toplam:7.4f}") yanitli = sum(1 for t in SORULAR.values() if t) print(f"okur sorusu {len(SORULAR)} | bir tür yanıtlıyor {yanitli} | " f"hiçbir tür yanıtlamıyor {len(SORULAR) - yanitli}") print() a_dogru, a_top = d2["açıklama"][1], d2["açıklama"][0] r_dogru, r_top = d2["referans"][1], d2["referans"][0] print(f"ikinci sürümde açıklama {a_dogru}/{a_top} = {a_dogru / a_top:.4f}, " f"referans {r_dogru}/{r_top} = {r_dogru / r_top:.4f}") print(f"ömür oranı {a_dogru / a_top / (r_dogru / r_top):.3f} kat") print() # Ayri tutulan iki tur, tek sayfada birlestirilirse okur ne gorur. BIRLESIK = ("öğretici", "referans") print(f"{'sayfa':<22s} {'iddia':>5s} {'doğru':>5s} {'bayat':>5s} {'güven':>7s}") for tur in BIRLESIK: t, dogru, bayat, _ = d2[tur] print(f"{tur + ' (ayrı)':<22s} {t:5d} {dogru:5d} {bayat:5d} " f"{dogru / t:7.4f}") t = sum(d2[x][0] for x in BIRLESIK) dogru = sum(d2[x][1] for x in BIRLESIK) print(f"{'ikisi tek sayfada':<22s} {t:5d} {dogru:5d} {t - dogru:5d} " f"{dogru / t:7.4f}") ``` ``` iddia 56 | tür 4 sürüm değişen yüzey öğretici nasıl yapılır açıklama referans doğru/bayat/sessiz doğru/bayat/sessiz doğru/bayat/sessiz doğru/bayat/sessiz 0 — 15/0/0 14/0/0 12/0/0 15/0/0 1 — 15/0/0 14/0/0 12/0/0 15/0/0 2 imza 12/3/1 9/5/2 11/1/1 2/13/13 soru yanıtlayan tür sürüm 2 güven nereden başlarım öğretici 12/15 0.8000 şunu nasıl yaparım nasıl yapılır 9/14 0.6429 bu neden böyle açıklama 11/12 0.9167 bu alanın tipi ne referans 2/15 0.1333 hangi sürümde değişti — — — bu neden çalışmıyor — — — okur sorusu 6 | bir tür yanıtlıyor 4 | hiçbir tür yanıtlamıyor 2 ikinci sürümde açıklama 11/12 = 0.9167, referans 2/15 = 0.1333 ömür oranı 6.875 kat sayfa iddia doğru bayat güven öğretici (ayrı) 15 12 3 0.8000 referans (ayrı) 15 2 13 0.1333 ikisi tek sayfada 30 14 16 0.4667 ``` #### İkinci Sürümün Okunması Birinci sürüm hiçbir şeye mal olmuyor: dört tür de yazıldıkları gibi duruyor. Bunun nedeni dokümana bakılmış olması değil, **en hızlı yüzeyin bile henüz kıpırdamamış olmasıdır.** Bayatlama sürekli bir aşınma değildir; basamak basamak gelir ve ilk basamak ikinci sürümdedir. İkinci sürümde değişen yüzey tek: **imza**. Faturalar ise şöyle bölünüyor — öğretici **3**, nasıl yapılır **5**, açıklama **1**, referans **13** iddia kaybediyor. Aynı olay, dört ayrı tutar. Kimse dört metinden birini daha özensiz yazmadı; dördü de aynı gün, aynı dikkatle yazıldı. Fark yalnız **neye bağlandıklarındadır.** Uçlar bunu tek satırda söylüyor. Elle yazılmış referans on beş iddiasından **13**'ünü kaybedip **2/15** ile kalıyor. Açıklama on iki iddiasının **11**'ini koruyor: **11/12**. Oranlar **0,1333** ve **0,9167**, aralarındaki fark **6,875 kat**. Aynı yazma çabası, altı katı aşan bir ömür. Bu sayının pratik karşılığı şudur: **bayatlama hızını tür değil, bağlanılan yüzey belirler.** "Referans çabuk eskir" cümlesi türün bir özelliği gibi görünür ama değildir; referans çabuk eskir çünkü iddialarının **13/15**'i en hızlı değişen yüzeye asılıdır. Aynı biçimde açıklama uzun yaşar çünkü **9/12**'si en yavaş yüzeye bağlıdır. Bir referansı yavaşlatmanın yolu daha dikkatli yazmak değil, iddiayı imzadan koparmaktır — ve bunun bir yolu vardır, dördüncü ders onu ölçer. Sessiz sütunu ikinci bir şey söylüyor. Öğreticinin **3** bayat iddiasının yalnız **1**'i sessiz, referansın **13** bayat iddiasının **13**'ü sessiz. Öğreticideki bozulma bir örneği kırdığı için bir gün birinin eline patlar; referanstaki bozulma hiçbir yerde patlamaz. **En çok kaybeden tür, kaybını en az duyuran türdür.** #### Karıştırmanın Bedeli Dört türü ayırmanın gerekçesi genellikle okurun aradığını bulması diye anlatılır. Son tablo ikinci ve daha sert bir gerekçe veriyor. Öğretici ile referans **tek bir sayfada** birleşirse sayfa **30** iddia taşır ve ikinci sürümde bunun **16**'sı bayattır: güven **0,4667**. Sayının okunması şudur: birleştirme ömürleri **ortalamaz**, hızlı olana çeker. Ayrı tutulduğunda öğreticiyi okuyan kişi **0,8000**'lik bir metin okuyordu; aynı içerik referansla aynı sayfaya konduğunda o okur artık **0,4667**'lik bir sayfa okuyor. Öğreticinin tek bir cümlesi bile değişmedi. Değişen şey, okurun neye baktığını ayırt edememesidir — sayfanın üstündeki dört doğru satırla altındaki on üç bayat satır aynı başlığın altında, aynı güvenle duruyor. Ayrım bu yüzden bir düzen tercihi değil, bir **ölçüm koşuludur**: iddialar türlere ayrılmadan hangi bölümün ne kadar dayandığı ölçülemez, ölçülemeyince de bakım hiçbir yere yönlendirilemez. Tek sayfa hangi bölümün çürüdüğünü saklar. #### Taksonominin Sınırı Alt tablo dört türü okurun tarafından ölçüyor. Okur dokümana altı ayrı soruyla gelir. Dördü temiz biçimde bir türe düşüyor: "nereden başlarım" öğreticiye, "şunu nasıl yaparım" nasıl yapılır metnine, "bu neden böyle" açıklamaya, "bu alanın tipi ne" referansa. Sayı net: **altı sorunun 4'ünü bir tür yanıtlıyor.** Ama yanıtlanmış olmak, doğru yanıtlanmış olmak değildir. Güven sütunu aynı ikinci sürümde şunu veriyor: "bu neden böyle" sorusunun yanıtı **0,9167** güvenilir, "bu alanın tipi ne" sorusununki **0,1333**. Okurun en kesin görünen sorusu — bir alanın tipi, ya öyledir ya değildir — en güvenilmez yanıtı alıyor. Referans kesin yazıldığı için güvenilir sanılır; oysa kesinlik, yalnız bayatlamanın hangi anda başladığını belirsizleştirmez, gizler. Geriye **2** soru kalıyor ve bunlar dört türün **hiçbirine** düşmüyor: **"hangi sürümde değişti"** ve **"bu neden çalışmıyor"**. Bu bir eksiklik değil, **taksonominin sınırıdır.** Dört tür ürünü **şimdiki hâliyle** anlatır; hiçbiri zamanı taşımaz, bu yüzden birincisi karşılıksız kalır. Dördü de doğru yolu anlatır; hiçbiri yanlış giden yoldan girmez, bu yüzden ikincisi karşılıksız kalır. İki soru da uydurulmuş değildir: birincisini az önceki tablo doğurdu — okur **2/15**'lik bir referansa bakarken hangi iddianın ne zaman düştüğünü sormak zorundadır. Kursun **beşinci** ve **altıncı** dersleri tam olarak bu iki soruyu kurar. #### Özet - Dört tür okurun ayrı anlarını karşılar: öğretici sonuç verir, nasıl yapılır görevi kapatır, açıklama gerekçe kurar, referans doğrulatır; öğretici okura doğrudan seslenen tek türdür. - Birinci sürüm hiçbir şeye mal olmaz; bayatlama basamaklıdır ve ilk basamak **ikinci sürümdedir**, çünkü en hızlı yüzey iki sürümde bir değişir. - Tek bir imza değişimi dört türe ayrı fatura keser: öğretici **3**, nasıl yapılır **5**, açıklama **1**, referans **13** iddia kaybeder. - Elle yazılmış referans **2/15** (**0,1333**), açıklama **11/12** (**0,9167**) ile kalır; ömür farkı **6,875 kat**. Bayatlama hızını tür değil, **bağlanılan yüzey** belirler. - Referansın **13** bayat iddiasının **13**'ü sessizdir; en çok kaybeden tür kaybını en az duyuran türdür. Öğretici ile referans tek sayfada birleştirilirse güven **0,8000**'den **0,4667**'ye iner: birleştirme ömürleri ortalamaz, hızlı olana çeker. - Altı okur sorusunun **4**'ü bir türe düşer, **2**'si hiçbirine: "hangi sürümde değişti" ve "bu neden çalışmıyor" — taksonominin sınırı budur. #### Sonraki Adım Buraya kadar ölçülen dört doküman ürünü anlatıyordu. Bir deponun içinde bunlardan başka belgeler de durur ve okurları farklıdır: depoya ilk kez bakan, katkı vermek isteyen, bir kararın neden öyle alındığını arayan. Sonraki ders bu belgeleri aynı ölçüye sokar — tanıtım dosyası, katkı rehberi ve mimari karar kaydı hangi yüzeylere bağlanır, hangisi bir sürümde çöker, hangisi yıllarca doğru kalır? ### Depo Belgeleri Source: https://academia.sh/tr/kurslar/teknik-yazarlik/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? ### API Referansı Source: https://academia.sh/tr/kurslar/teknik-yazarlik/api-referansi Referansın 15 iddiasının 13'ü imzaya bağlıdır ve elle yazıldığında altıncı sürümde 0/15 kalır; kaynaktan üretildiğinde aynı sürümde 13/15 kalır, kurtarılamayan 2 iddia ad yüzeyindedir ve referans hiç örnek taşımadığı için bayatlayan iddialarının hepsi sessizdir. Önceki ders üç depo belgesini ölçtü ve üçünde de imza payı yarıyı geçmiyordu. Deponun en kalabalık imza yığını başka bir yerde duruyor. İkinci ders arayüz referansını ikinci sürümde **2/15** ile bırakmıştı ve bunun nedeni yazarın özensizliği değildi: on beş iddianın **13**'ü en hızlı değişen yüzeye asılıydı. Bu ders o türü kendi düzeniyle ele alır. Önce referansın nasıl bölümlendiği kurulur — uç nokta, parametre, hata — sonra tek bir soru ölçülür: bu iddialar **elle yazılmak zorunda mı?** Yazılmazsa ne kadarı kurtulur ve geriye tam olarak ne kalır? #### Referansın Üç Bölümü Referans okunmak için değil, bakılmak için yazılır. Okur ne aradığını bilir ve tek bir hücreyi doğrulamak ister. Bu yüzden referansın düzeni anlatı değil, **tablodur**; ve tablo olmasının tek gerekçesi biçim tercihi değildir: tablo, her hücrenin tek bir iddia taşımasını ve eksiğinin göze çarpmasını sağlar. Tablonun üç bölümü vardır. **Uç nokta** çağrının kimliğini verir: yöntem, yol ve yolun içindeki değişken parçalar. **Parametre** her girdinin adını, nereden alındığını, tipini, zorunluluğunu ve varsayılanını verir. **Hata** ise çağrının başarısız olabileceği yolları sayar: durum kodu, hata kodu ve hangi koşulda döndüğü. ```text # kurgu ürünün arayüz referansından bir giriş # örnek metin, çalıştırılmamıştır GET /olcum/{istasyon}/ozet bu uç nokta referansta "istasyon özeti" adıyla geçer istasyon yol parametresi dizgi zorunlu aralik sorgu parametresi tamsayı varsayılan 60, alt sınır 1 bicim sorgu parametresi dizgi "duz" | "tablo" 200 ozet nesnesi döner 404 istasyon-bulunamadi verilen istasyon tanımlı değil 422 aralik-gecersiz aralık alt sınırın altında ``` Bu girişte yazılan hemen her şey arayüzün **biçimidir**: yol kalıbı, parametre adları, tipler, varsayılanlar, durum kodları. Yalnız iki şey biçim değil — uç noktanın referansta anıldığı ad ve hata kodlarının adları. İkisi de **ad** yüzeyindedir ve az sonra tek başlarına bir sonuca dönüşecekler. #### Parametre Satırının Alanları Bir parametre satırı altı şey söylemek zorundadır ve eksiği okurun kaynağa gitmesine yol açar: **ad**, **konum** (yolda mı, sorguda mı, gövdede mi), **tip**, **zorunluluk**, **varsayılan** ve **sınır**. Yukarıdaki girişte `aralik` satırı altısını da taşıyor; `bicim` satırı varsayılanı taşımıyor ve okur "vermezsem ne olur" sorusuyla baş başa kalıyor. Bu altı alanın hepsi imza yüzeyindedir, dolayısıyla hepsi iki sürümde bir bayatlama riskini taşır. Ama aralarında bir ayrım vardır: ilk dördü kaynaktaki bildirimden okunabilir, **varsayılan** ve **sınır** çoğu zaman kodun gövdesinde durur ve bildirimden okunmaz. Bu ayrım üretimin ne kadarını kurtarabileceğini önceden belirler; ölçüm bunu bir bütün olarak sayacak, ama uygulamada üretimin kapsamı tam olarak buradan başlar. Satırın taşımadığı bir şey de kasıtlıdır: **neden**. `aralik` parametresinin alt sınırının neden bir olduğu referansa yazılmaz, açıklamaya yazılır. Yazılırsa iki yerde durur, ikisi ayrı hızda bayatlar ve okur hangisinin güncel olduğunu bilemez. #### Durum Kodu ve Hata Kodu Hata bölümündeki iki sütun aynı şeyi söylemez ve karıştırılmaları pahalıdır. **Durum kodu** kabaca sınıflandırır: istek yanlış mıydı, kaynak yok muydu, sunucu mu çöktü. **Hata kodu** ise tek bir durumu adlandırır — `istasyon-bulunamadi` ile `olcum-bulunamadi` aynı durum kodunu döndürebilir ve okurun yapacağı iş bambaşkadır. Buradan pratik bir sonuç çıkar: istemci **durum koduna göre değil, hata koduna göre dallanır.** Yani referansın en çok güvenilen hücresi, ölçümde **ad** yüzeyinde duran hücredir. Sayıca azdır — on beş iddianın ikisi — ama üzerine kod yazılan iddia odur. Bayatladığında dallanma sessizce yanlış kola girer; ne bir tip hatası verir ne bir uyarı. Hata bölümü çoğu referansta en zayıf bölümdür ve nedeni ölçülebilir. Başarılı yol bir kez yazılır ve her çağrıda sınanır; başarısız yollar ise yazılmayı bekler ve kimse onları çağırmaz. Oysa referansa bakan okur genellikle **zaten bir hata almış** kişidir; aradığı hücre tam olarak orada durur. Sözleşmenin makine okunur biçimde tanımlanması ve sözleşmenin testle doğrulanması **Web API Tasarımı** kursunun konusudur ve burada tekrarlanmaz. Bu derste referans bir sözleşme aracı olarak değil, **bakımı gereken bir metin** olarak ölçülür: kaç iddia taşıyor, ne kadar dayanıyor, kaç tanesi kurtarılabilir. #### Elle Yazmak ve Üretmek Aynı referans iki yolla var edilebilir. **Elle yazılan** referansta her hücre bir insanın yazdığı bir cümledir. Kaynakta bir parametrenin tipi değiştiğinde referanstaki hücre eski tipi göstermeye devam eder; hiçbir şey bu ikisini birbirine bağlamaz. **Kaynaktan üretilen** referansta ise hücreler metnin içinde değil, kaynağın kendisinde durur ve her yayımda yeniden okunur. Tip değişirse hücre de değişir, çünkü hücre zaten kaynağın kopyasıdır. Üretimin kurtardığı şey belirlidir: **yalnız kaynakta yazılı olan.** Bir parametrenin adı, tipi ve varsayılanı kaynaktadır. Bir uç noktanın referansta hangi adla anılacağı kaynakta değildir; bir hata kodunun insan tarafından okunacak adı da çoğu zaman değildir. Bunlar üretimin dışında kalır ve elle yazılan metinde durur. Ölçüm bu ayrımı sayıyla verecek. Ölçümün varsayımları: - **DT27** — Ölçülen küme, ortak kurgunun **referans** türüdür: **15** iddia, **13**'ü imza, **2**'si ad yüzeyinde. Bu karışım değiştirilmez. - **DT28** — Referansın **akış** ve **kavram** iddiası **yoktur**. Referans sıra anlatmaz ve gerekçe kurmaz; bu, türün tanımından gelir ve dersin bir seçimi değildir. - **DT29** — On beş iddia üç bölüme dağıtılır: uç nokta **4**, parametre **7**, hata **4**. Bölümleme yüzey karışımını değiştirmez, yalnız iddiaları adreslenebilir kılar. - **DT30** — Referansın çalıştırılabilir örneğe gömülü iddia oranı **0,00**'dır. Referans örnek taşımaz; bu yüzden bayatlayan her referans iddiası **sessizdir**. - **DT31** — Yüzey sıklıkları değişmez: imza **2**, akış **3**, ad **5**, kavram **12** sürümde bir. - **DT32** — **Üretilen referansta imza iddiaları hiç bayatlamaz.** Kaynaktan okundukları için kaynakla birlikte değişirler; aradaki gecikme bu ölçümde sıfır sayılır. - **DT33** — Üretim **ad** yüzeyini kurtarmaz: uç noktanın anıldığı ad ve hata kodunun okunur adı kaynakta durmaz, elle yazılan metinde durur. - **DT34** — Üretim **akış** yüzeyini de kurtarmaz; ama bu referansta ölçülemez, çünkü referansın akış iddiası yoktur. Akışa bağlı iddialar öteki türlerde ölçülür. - **DT35** — Ölçüm **0, 1, 2, 3, 5, 6 ve 12**'nci sürümleri kurar. - **DT36** — Kümenin çözünürlüğü **1/15**'tir; tek iddialık farkların altı bu kümeyle savunulamaz. #### Ölçüm ```python """Arayuz referansi: elle yazilan ile kaynaktan uretilenin omru. Bolum 1 - referansin 15 iddiasi bolumlere ve yuzeylere nasil dagiliyor. Bolum 2 - surum boyunca elle yazilan ve uretilen referansta dogru/bayat/sessiz. """ SIKLIK = {"imza": 2, "akis": 3, "ad": 5, "kavram": 12} SURUMLER = (0, 1, 2, 3, 5, 6, 12) # Referansin 15 iddiasi: hangi bolumde, hangi yuzeye bagli. # Toplam imza 13, ad 2 - ortak tanimdaki referans karisiminin ta kendisi. BOLUMLER = { "uç nokta": {"imza": 3, "ad": 1}, "parametre": {"imza": 7, "ad": 0}, "hata": {"imza": 3, "ad": 1}, } # Referansin gomulu iddia orani sifirdir: referans calistirilabilir ornek tasimaz. ORNEKLI = 0.00 def iddialar(): liste, no = [], 0 for bolum, dagilim in BOLUMLER.items(): for yuzey, adet in dagilim.items(): for _ in range(adet): no += 1 liste.append({"no": no, "bolum": bolum, "yuzey": yuzey, "gomulu": ORNEKLI >= 1}) return liste def bayat_mi(i, surum): return surum // SIKLIK[i["yuzey"]] >= 1 def olc(liste, surum, uretilen): """Uretilen referansta imza iddialari kaynaktan geldigi icin bayatlamaz.""" bayat = [i for i in liste if bayat_mi(i, surum) and not (uretilen and i["yuzey"] == "imza")] sessiz = [i for i in bayat if not i["gomulu"]] return len(liste), len(liste) - len(bayat), len(bayat), len(sessiz) L = iddialar() print(f"referans iddiası {len(L)} | örneğe gömülü " f"{sum(i['gomulu'] for i in L)}") print() print(f"{'bölüm':<12s} {'iddia':>5s} {'imza':>5s} {'ad':>4s} {'akış':>5s} " f"{'kavram':>6s}") for b in BOLUMLER: g = [i for i in L if i["bolum"] == b] print(f"{b:<12s} {len(g):5d} " + " ".join(f"{sum(1 for i in g if i['yuzey'] == y):>{w}d}" for y, w in zip(("imza", "ad", "akis", "kavram"), (5, 4, 5, 6)))) print(f"{'toplam':<12s} {len(L):5d} " + " ".join(f"{sum(1 for i in L if i['yuzey'] == y):>{w}d}" for y, w in zip(("imza", "ad", "akis", "kavram"), (5, 4, 5, 6)))) print() print(f"{'sürüm':>5s} {'elle yazılan':>20s} {'üretilen':>20s}") print(f"{'':5s} {'doğru/bayat/sessiz':>20s} {'doğru/bayat/sessiz':>20s}") for s in SURUMLER: e = olc(L, s, False) u = olc(L, s, True) print(f"{s:5d} {'{}/{}/{}'.format(*e[1:]):>20s} " f"{'{}/{}/{}'.format(*u[1:]):>20s}") print() print(f"{'bölüm':<12s} {'6. sürüm elle':>13s} {'6. sürüm üretilen':>17s} " f"{'kurtarılan':>10s}") for b in BOLUMLER: g = [i for i in L if i["bolum"] == b] e, u = olc(g, 6, False), olc(g, 6, True) print(f"{b:<12s} {f'{e[1]}/{e[0]}':>13s} {f'{u[1]}/{u[0]}':>17s} " f"{u[1] - e[1]:10d}") print() kalan = [i for i in L if bayat_mi(i, 6) and i["yuzey"] != "imza"] print("6. sürümde üretilen referansta bayat kalan iddialar:", [(i["bolum"], i["yuzey"]) for i in kalan]) print(f"üretimin kurtardığı yüzey: imza " f"({sum(1 for i in L if i['yuzey'] == 'imza')} iddia) | kurtaramadığı: " f"{', '.join(sorted({i['yuzey'] for i in kalan}))} ({len(kalan)} iddia)") ``` ``` referans iddiası 15 | örneğe gömülü 0 bölüm iddia imza ad akış kavram uç nokta 4 3 1 0 0 parametre 7 7 0 0 0 hata 4 3 1 0 0 toplam 15 13 2 0 0 sürüm elle yazılan üretilen doğru/bayat/sessiz doğru/bayat/sessiz 0 15/0/0 15/0/0 1 15/0/0 15/0/0 2 2/13/13 15/0/0 3 2/13/13 15/0/0 5 0/15/15 13/2/2 6 0/15/15 13/2/2 12 0/15/15 13/2/2 bölüm 6. sürüm elle 6. sürüm üretilen kurtarılan uç nokta 0/4 3/4 3 parametre 0/7 7/7 7 hata 0/4 3/4 3 6. sürümde üretilen referansta bayat kalan iddialar: [('uç nokta', 'ad'), ('hata', 'ad')] üretimin kurtardığı yüzey: imza (13 iddia) | kurtaramadığı: ad (2 iddia) ``` #### Üretimin Kurtardığı ve Kurtaramadığı Orta tablo dersin ana sayısını veriyor. Altıncı sürümde elle yazılan referans **0/15**; kurtarılan tek iddia yok, on beşinin on beşi bayat. Aynı sürümde üretilen referans **13/15**. Fark **13** iddiadır ve tamamı **parametre ile uç noktanın imza hücrelerinden** gelir. Alt tablo farkı bölümlere dağıtıyor: parametre bölümü elle **0/7**, üretilerek **7/7** — tamamen kurtuluyor, çünkü içindeki her hücre kaynakta yazılı. Uç nokta **0/4**'ten **3/4**'e, hata bölümü **0/4**'ten **3/4**'e çıkıyor. Her iki bölümde de kurtarılamayan bir iddia kalıyor. Kurtarılamayan iki iddianın kim olduğu son satırda açıkça yazıyor: biri uç noktanın referansta anıldığı **ad**, öteki hata kodunun okunur **adı**. İkisi de **ad yüzeyinde**. Üretimin sınırı burada net biçimde çiziliyor: **üretim kaynakta yazılı olanı kurtarır, insanın uydurduğunu kurtarmaz.** Bir adın ne olduğuna kaynak karar vermez. Aynı sınır **akış** yüzeyi için de geçerlidir — çağrıların hangi sırayla yapılacağı kaynaktan üretilemez — ama bu referansta ölçülemez, çünkü referansın akış iddiası **0**'dır. Bu bir ölçüm eksiği değil, türün tanımı: referans sıra anlatmaz. Aynı zamanda referansın en büyük boşluğudur ve kursun altıncı dersi tam oradan girecek. Sessiz sütunu ise dersin rahatsız edici bulgusu. Referansın gömülü iddiası **0** olduğu için her satırda bayat sayısı ile sessiz sayısı **aynı**: elle yazılanda **15/15**, üretilende **2/2**. Yani üretim bayat iddia sayısını on beşten ikiye indiriyor ama **sessizlik oranını hiç değiştirmiyor** — kalan iki iddia da kimseye hiçbir şey söylemeden yanlış duruyor. Bu, üretimi küçümsemek için değil, ne yaptığını doğru adlandırmak için önemli. Üretim bir **doküman denetimi** değil, bir **kopyalama** düzeneğidir: kaynakla metin arasındaki bağı kurar, metnin doğruluğunu kimseye bildirmez. On üç iddia kurtarıldığında geriye kalan iki iddia, tam olarak eskisi kadar sessizdir; üstelik referansın geri kalanı artık güvenilir olduğu için o ikisine kimsenin şüpheyle bakması da beklenmez. **Kurtarılan iddialar, kurtarılamayanları gizler.** Kurtarılamayan ikinin **hangi** iki iddia olduğu ayrıca önemli. Bir önceki bölüm, istemcinin durum koduna göre değil hata koduna göre dallandığını söylemişti; kurtarılamayan iddialardan biri tam olarak o hata kodunun adıdır. Yani **13/15** oranı pratik kurtarışı olduğundan iyi gösteriyor: kurtarılan on üç iddia okurun doğrulamak için baktığı hücrelerdir, kurtarılamayan ikisi ise okurun üzerine kod yazdığı hücreler. Sayı payda üzerinden okunursa üretim kümenin **0,8667**'sini kurtarmış görünür; etki üzerinden okunursa en pahalı iki iddiayı olduğu yerde bırakmıştır. Ölçünün kendisi bunu söylemez — ölçü iddia sayar, iddiaların ağırlığını saymaz — ve bu, iddia sayımının bilinmesi gereken sınırıdır. İkinci ve üçüncü sürüm satırları son bir ayrıntı veriyor: üretilen referans orada **15/15** duruyor, yani ilk üç sürüm boyunca hiç kayıp vermiyor. Elle yazılan aynı noktada **2/13/13**. Üretimin kazancı ilk imza değişiminde başlıyor ve **beşinci sürüme kadar tam** kalıyor; ad yüzeyi ilk kez orada değişiyor ve fark **15**'ten **13**'e iniyor. Ondan sonra sabit: on ikinci sürümde de **13/15**. Üretilen referans bir noktadan sonra **daha fazla bozulmaz**, çünkü bozulabilecek her şeyi zaten bozmuştur. #### Özet - Referans tablodur, anlatı değil; üç bölümü vardır — uç nokta, parametre, hata — ve hata bölümü en zayıf bölümdür çünkü kimse başarısız yolları çağırmaz. - Referansın **15** iddiasının **13**'ü imzaya, **2**'si ada bağlıdır; akış ve kavram iddiası **yoktur** ve gömülü iddiası **0**'dır. - Elle yazılan referans altıncı sürümde **0/15** verir; kaynaktan üretilen aynı sürümde **13/15** verir. Fark, parametre bölümünün **7/7** ve iki bölümün **3/4**'lük kurtarışından gelir. - Kurtarılamayan **2** iddia **ad** yüzeyindedir — uç noktanın anıldığı ad ve hata kodunun okunur adı; üretim kaynakta yazılı olanı kurtarır, insanın uydurduğunu kurtarmaz. - Referans hiç örnek taşımadığı için bayat sayısı ile sessiz sayısı her satırda eşittir; üretim bayatı **15**'ten **2**'ye indirir, sessizlik oranını **hiç** değiştirmez. - İstemci durum koduna göre değil **hata koduna** göre dallanır; kurtarılamayan iki iddiadan biri odur. İddia sayımı iddiaların ağırlığını saymaz ve bu, ölçünün bilinmesi gereken sınırıdır. #### Sonraki Adım Buraya kadar dört tür ve depo belgeleri ürünün **bugünkü hâlini** anlattı. Bu dersin tablosu okura yeni bir soru borçlandırdı: elinde **13/15**'lik bir referans varken kalan ikisinin **ne zaman** düştüğünü nereden bilecek? İkinci ders bu soruyu adıyla koymuştu — "hangi sürümde değişti" hiçbir türe düşmüyordu. Sonraki ders o boşluğu kapatan metni ölçer: sürüm notu. Soru şu olacak — değişikliklerin listesi ile değişikliklerin **anlamının** listesi arasındaki fark, kaç iddiayı okur için tarihlenebilir kılıyor? ### Sürüm Notları Source: https://academia.sh/tr/kurslar/teknik-yazarlik/surum-notlari Dört tür ürünü bugünkü hâliyle anlatır ve hiçbiri zamanı taşımaz; ham değişiklik listesi on ikinci sürümde 56 bayat iddianın 17'sini tarihlendirir ve sessiz olanların 0'ını, aynı dokuz girdiye yanlışlanan iddia yazıldığında 56'sının 56'sı ve sessiz 39'un 39'u tarihlenebilir olur. Önceki ders üretilen referansı altıncı sürümde **13/15** ile bıraktı ve okura bir soru borçlandırdı: kalan ikisi **ne zaman** düştü? İkinci ders bu sorunun adını çoktan koymuştu — altı okur sorusundan biri, "hangi sürümde değişti", dört türün hiçbirine düşmüyordu. Bu ders o boşluğu kapatan metni ölçer. Sorulan şey sürüm notunun nasıl yayımlandığı değil, **neyi tarihlenebilir kıldığıdır**: bayat bir iddiaya bakan okur, o cümlenin hangi sürümde yanlışlandığını nereden öğrenecek? #### Zamanı Taşıyan Tek Metin Dört türün ortak bir özelliği vardır ve bugüne kadar hiç adlandırılmadı: **hepsi şimdiki zamanla yazılır.** Öğretici bugün nasıl başlanacağını, nasıl yapılır bugün nasıl yapılacağını, açıklama bugün neden öyle olduğunu, referans bugün hangi alanın hangi tipte olduğunu söyler. Dördü de geçmişi silen metinlerdir; bir alanın tipi değiştiğinde referans eski tipi anmaz, yenisini yazar ve eskisi hiç var olmamış gibi olur. Bu, dört tür için doğru bir tasarımdır. Referansın içine tarihçe konursa okur her hücrede hangi satırın bugüne ait olduğunu ayırmak zorunda kalır ve referansın tek işlevi — hızlı doğrulama — kaybolur. Ama bir bedeli var: **hiçbir tür zamanı taşımadığı için, hiçbiri "ne zaman değişti" sorusunu yanıtlayamaz.** Sürüm notu tam olarak bu boşluğa oturur ve ötekilerden farkı içeriğinde değil, **indeksinde** durur. Dört tür konuya göre indekslenir: okur bir konu arar, o konunun bölümünü açar. Sürüm notu **zamana göre** indekslenir: okur bir sürüm arar, o sürümün girdisini açar. Bu yüzden sürüm notu dört türün beşincisi değil, ayrı bir eksende duran ayrı bir türdür. Sürümün hangi hattan geçerek yayımlandığı, notun alanlarının okurun altı sorusunu nasıl karşıladığı ve etiketin neyi işaretlediği **Kod İnceleme ve Ekip Süreci** kursunda ölçüldü ve burada tekrarlanmaz. Orada ölçülen şey notun **okura** ne söylediğiydi; burada ölçülen şey notun **öteki dokümanlara** ne yaptığıdır. #### İki Liste Aynı sürüm iki biçimde yazılabilir ve ikisi de aynı olaydan üretilir. ```text # kurgu ürünün sürüm notundan iki biçim # örnek metin, çalıştırılmamıştır ham değişiklik listesi s6 ölçüm çağrısının seçenek adları düzenlendi s6 özet akışında adım sırası değişti anlam listesi s6 ölçüm çağrısının seçenek adları düzenlendi yanlışlanan: referanstaki parametre satırları, nasıl yapılır metnindeki çağrı örnekleri s6 özet akışında adım sırası değişti yanlışlanan: öğreticinin üçüncü ve dördüncü adımı ``` İki liste aynı sayıda girdi taşıyor. Fark tek bir alanda: ikincisi her girdiye **ne yanlışlandığını** yazıyor. Bu alan sıradan bir ayrıntı gibi görünür ama yönü tersine çevirir. Ham liste **değişikliğin tarafından** yazılmıştır: yapılan işi anlatır. Anlam listesi **dokümanın tarafından** yazılmıştır: hangi cümlelerin bugünden itibaren yanlış olduğunu söyler. Bu ayrımın okur üzerindeki etkisi, notun ne zaman işe yaradığıyla ilgilidir. Ham listeye bakan okur, aradığının ne olduğunu **zaten bilmek zorundadır**. Bir örnek elinde patladıysa hangi çağrının bozulduğunu bilir ve listede o çağrıyı arar; bulunca tarihi de öğrenir. Ama hiçbir şey patlamadıysa listeye bakmak için bir nedeni yoktur, çünkü hangi cümlenin yanlışlandığını bilmiyordur. **Ham liste, arızayı zaten duymuş okura yarar.** #### Notun Boyu Bir not yazmanın maliyeti girdi sayısıdır ve o sayı sanıldığı kadar büyük değildir. On iki sürüm boyunca yüzeyler kendi sıklıklarında değişir; bazı sürümlerde hiçbir yüzey değişmez, bazılarında birden fazlası aynı anda değişir. Not yalnız **değişimin olduğu** sürümlerde girdi taşır. Ölçüm bu girdi sayısını ve girdi başına tarihlenen iddia sayısını da verecek. Girdinin **ne zaman** yazıldığı da bir tercihtir ve sonucu belirler. Not yayım gününde toplu olarak yazılırsa, yazan kişi geriye dönüp her değişikliğin hangi cümleleri yanlışladığını çıkarmak zorunda kalır; bu bilgi o noktada artık kolay bulunmaz ve pratikte yazılmaz. Girdi değişiklik anında yazılırsa, yanlışlanan cümleyi bilen kişi zaten oradadır: değişikliği yapan kişi. Aradaki fark bir disiplin sorusu gibi görünür ama ölçülen sütunu doğrudan belirler — aşağıdaki tabloda anlam listesini ham listeden ayıran tek alan, yalnız o anda ucuzdur. Ölçümün varsayımları: - **DT37** — Ölçülen küme kursun kurgu kümesidir: **56** iddia, dört tür, dört yüzey ve **17** gömülü örnek. Karışım değiştirilmez. - **DT38** — Yüzey sıklıkları sabittir: imza **2**, akış **3**, ad **5**, kavram **12** sürümde bir. Bir yüzey, sıklığının katı olan her sürümde bir kez değişir. - **DT39** — Bir iddianın **düşüş sürümü**, bağlandığı yüzeyin ilk değiştiği sürümdür ve kurguyu biz yazdığımız için bilinir. Okur bunu ancak yazılmışsa bilir. - **DT40** — Sürüm notu, en az bir yüzeyin değiştiği her sürüm için bir girdi taşır. Hiçbir yüzeyin değişmediği sürümlerde girdi yoktur. - **DT41** — Üç not biçimi denenir: **sürüm notu yok**, **ham değişiklik listesi** ve **anlam listesi**. Üçü de aynı olaylardan üretilir. - **DT42** — **Sürüm notu yokken** bayat bir iddia tarihlenemez; dört türün hiçbiri zaman taşımaz. - **DT43** — **Ham değişiklik listesi** yalnız yapılanı yazar. Bir iddiayı tarihlenebilir kılması için okurun o iddiadan şüphelenmiş olması gerekir; bu ölçümde şüphe yalnız **gömülü** bir iddia kırıldığında doğar. - **DT44** — **Anlam listesi** her girdiye yanlışlanan iddiaları yazar; okurun şüphelenmesi gerekmez, bayat olan her iddia tarihlenebilir olur. - **DT45** — Bir iddia **tarihlenebilir** sayılmak için önce **bayat** olmalıdır; henüz doğru olan iddia bu sütuna girmez. - **DT46** — Kümenin çözünürlüğü **1/56**'dır; not girdisi ölçeğinde **1/9**'dur. #### Ölçüm ```python """Surum notu: bayat bir iddianin ne zaman dustugu okur icin tarihlenebilir mi. Bolum 1 - on iki surumdeki degisim olaylari ve notun satir sayisi. Bolum 2 - uc not bicimi altinda tarihlenebilir bayat iddia ve sessiz olani. """ 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} SURUMLER = (2, 3, 5, 6, 12) SON = 12 def iddialar(): liste, no = [], 0 for tur, dagilim in TURLER.items(): gomulu_hedef = 0 for yuzey, adet in dagilim.items(): for _ in range(adet): no += 1 gomulu_hedef += ORNEKLI[tur] gomulu = gomulu_hedef >= 1 and yuzey != "kavram" if gomulu: gomulu_hedef -= 1 liste.append({"no": no, "tur": tur, "yuzey": yuzey, "gomulu": gomulu, "dusen": SIKLIK[yuzey]}) return liste def olaylar(son=SON): """Her surumde hangi yuzeyler degisti: notun yazacagi girdiler.""" return [(s, [y for y in SIKLIK if s % SIKLIK[y] == 0]) for s in range(1, son + 1) if any(s % SIKLIK[y] == 0 for y in SIKLIK)] # Not bicimleri: bayat bir iddiayi hangi kosulda tarihlenebilir kiliyorlar. BICIMLER = { "sürüm notu yok": lambda i: False, "ham değişiklik listesi": lambda i: i["gomulu"], "anlam listesi": lambda i: True, } L = iddialar() O = olaylar() print(f"iddia {len(L)} | örneğe gömülü {sum(i['gomulu'] for i in L)} | " f"on iki sürümde değişim olayı {sum(len(y) for _, y in O)} | " f"not girdisi {len(O)}") print("not girdileri: " + "; ".join(f"s{s}: {', '.join(y)}" for s, y in O)) print() print(f"{'sürüm':>5s} {'bayat':>5s} {'sessiz':>6s} " + " ".join(f"{ad:>23s}" for ad in BICIMLER)) print(f"{'':5s} {'':5s} {'':6s} " + " ".join(f"{'tarihlenebilir/sessizi':>23s}" for _ in BICIMLER)) for s in SURUMLER: bayat = [i for i in L if s // SIKLIK[i["yuzey"]] >= 1] sessiz = [i for i in bayat if not i["gomulu"]] satir = f"{s:5d} {len(bayat):5d} {len(sessiz):6d} " for ad, kural in BICIMLER.items(): t = [i for i in bayat if kural(i)] ts = [i for i in t if not i["gomulu"]] satir += f" {f'{len(t)}/{len(ts)}':>23s}" print(satir) print() print(f"{'not biçimi':<24s} {'girdi':>5s} {'tarihlenen iddia':>16s} " f"{'girdi başına':>12s} {'sessizden':>9s}") son_bayat = [i for i in L if SON // SIKLIK[i["yuzey"]] >= 1] son_sessiz = [i for i in son_bayat if not i["gomulu"]] for ad, kural in BICIMLER.items(): t = [i for i in son_bayat if kural(i)] ts = [i for i in t if not i["gomulu"]] girdi = 0 if ad == "sürüm notu yok" else len(O) pay = len(t) / girdi if girdi else 0 print(f"{ad:<24s} {girdi:5d} {f'{len(t)}/{len(son_bayat)}':>16s} " f"{pay:12.3f} {f'{len(ts)}/{len(son_sessiz)}':>9s}") ``` ``` iddia 56 | örneğe gömülü 17 | on iki sürümde değişim olayı 13 | not girdisi 9 not girdileri: s2: imza; s3: akis; s4: imza; s5: ad; s6: imza, akis; s8: imza; s9: akis; s10: imza, ad; s12: imza, akis, kavram sürüm bayat sessiz sürüm notu yok ham değişiklik listesi anlam listesi tarihlenebilir/sessizi tarihlenebilir/sessizi tarihlenebilir/sessizi 2 22 17 0/0 5/0 22/17 3 38 24 0/0 14/0 38/24 5 45 28 0/0 17/0 45/28 6 45 28 0/0 17/0 45/28 12 56 39 0/0 17/0 56/39 not biçimi girdi tarihlenen iddia girdi başına sessizden sürüm notu yok 0 0/56 0.000 0/39 ham değişiklik listesi 9 17/56 1.889 0/39 anlam listesi 9 56/56 6.222 39/39 ``` #### Tarihlenebilirliğin Okunması İlk satır notun boyunu veriyor: on iki sürümde **13** değişim olayı var ama not yalnız **9** girdi taşıyor. Üç sürümde birden fazla yüzey aynı anda değişiyor — altıncı sürümde imza ile akış, onuncuda imza ile ad, on ikincide üçü birden. Üç sürümde ise hiçbir şey değişmiyor ve not o sürümler için girdi taşımıyor. Üst tablonun sol sütunları kursun tanıdık sayılarını veriyor: bayat iddia ikinci sürümde **22**, üçüncüde **38**, beşincide **45**, on ikincide **56**; sessiz olanlar sırasıyla **17**, **24**, **28** ve **39**. Sağdaki üç sütun aynı satırlarda okurun ne tarihlendirebildiğini gösteriyor. **Sürüm notu yokken** her satırda **0/0**. Bu, dersin başındaki savın sayısal karşılığıdır: dört tür ne kadar iyi yazılırsa yazılsın, tek bir iddianın ne zaman yanlışlandığını söyleyemez. **Ham değişiklik listesi** ikinci sürümde **5**, üçüncüde **14**, beşincide **17** tarihlendiriyor ve orada duruyor. On ikinci sürümde bayat iddia **56**'ya çıktığı hâlde ham liste hâlâ **17**'de kalıyor. Sayı tesadüf değil: gömülü iddia sayısı **17**'dir ve ham liste tam olarak onları tarihlendirir, bir tanesini bile fazla değil. Beşinci sürümden sonra ham listenin eğrisi düzleşiyor: değişiklikler sürüyor, not büyüyor, tarihlenen iddia sayısı sabit kalıyor. Not yazmaya harcanan emek artıyor, karşılığı artmıyor. Asıl bulgu ise ham listenin sağdaki payında: **0/39**. Sessiz bayatlayan otuz dokuz iddianın **hiçbiri** ham değişiklik listesiyle tarihlenemiyor. Neden açık — ham liste yalnız şüphelenmiş okura yarar ve sessiz bir iddia kimseyi şüphelendirmez. Ham liste, işe yaraması için okurun zaten bilmesini gerektiren bir metindir; bilmeyen okur için **hiçbir şey** yapmaz. **Anlam listesi** aynı satırlarda bayat sayısının tamamını tarihlendiriyor: **22/17**, **38/24**, **45/28** ve **56/39**. Son sütun bunu tek bir oranla veriyor — sessiz otuz dokuz iddianın **39**'u tarihlenebilir hâle geliyor. Alt tablo bedeli ölçüyor ve dersin en pratik sonucu orada. **İki biçim de 9 girdi taşıyor.** Anlam listesi daha uzun bir not değildir; aynı dokuz girdiye fazladan bir alan yazılmış hâlidir. Buna karşılık girdi başına tarihlenen iddia **1,889**'dan **6,222**'ye çıkıyor — üç katından fazlası. Yazma emri tek cümleyle söylenebilir: **girdiye ne yapıldığını yazmak yetmez, neyi yanlışladığını yazmak gerekir.** Bu, kursun boyunca sessiz bayatlamaya ulaşan ilk düzenektir ve nasıl ulaştığı önemli. Sessiz bayatlamayı görünmez kılan şey, dokümanın kendisinden hiçbir sinyal gelmemesiydi. Anlam listesi sinyali dokümandan değil, **değişikliğin kendisinden** alır: kod değişirken hangi cümlelerin yanlışlandığı o anda bilinir, sonradan bilinmez. Notun tuttuğu şey bu andır. Yazılmazsa kaybolur ve bir daha üretilemez. #### Notun Kapatmadığı Tablo notun ne yaptığını söylüyor; ne yapmadığını da yazmak gerekir, çünkü **56/56** görüntüsü fazlasını vaat ediyor. Birincisi: tarihlemek düzeltmek değildir. Anlam listesi okura "referanstaki parametre satırı altıncı sürümde yanlışlandı" der; **doğrusunun ne olduğunu** demez. Okur yanlışı öğrenir, doğruyu öğrenmez. Bu yine de büyük bir kazançtır — yanlış olduğunu bilmek, yanlışı doğru sanmaktan iyidir — ama iddiayı doğru kalanlar sütununa geri taşımaz. Tabloda **doğru** sütunu hiçbir not biçiminde değişmiyor; değişen yalnız bayat olanın görünürlüğü. İkincisi: notun okuru dokümanın okuru değildir. Sürüm notunu izleyen kişi ürünü zaten kullanandır. Bugün ilk kez gelen okur, geçmiş notları okumaz; onun için doküman yine tarihsizdir ve **17** gömülü iddia dışında hiçbir şey ona bir uyarı vermez. Anlam listesi bayatlamayı **bakım yapan** için görünür kılar, **yeni okur** için kılmaz. Üçüncüsü: not ancak yazıldığı kadar doğrudur ve kendisi de bir dokümandır. Girdilerindeki "yanlışlanan" alanı, yazıldığı andaki doküman yapısına bağlıdır; bölümler yeniden düzenlendiğinde o alan da bayatlar. Notun kendisi bu ölçümün dışında tutuldu, ama gerçek bir depoda o da sayılan kümeye girer. #### Özet - Dört tür şimdiki zamanla yazılır ve konuya göre indekslenir; sürüm notu **zamana göre** indekslenen ayrı bir türdür ve "hangi sürümde değişti" sorusunu yalnız o kapatır. - On iki sürümde **13** değişim olayı, notta **9** girdi eder; bazı sürümlerde birden çok yüzey aynı anda değişir, bazılarında hiçbiri değişmez. - Sürüm notu yokken bayat iddiaların **0/56**'sı tarihlenebilir; ham değişiklik listesiyle **17/56** ve bu sayı gömülü iddia sayısına eşittir, on ikinci sürümde de büyümez. - Ham değişiklik listesi sessiz bayatlayan **39** iddianın **0**'ını tarihlendirir; yalnız arızayı zaten duymuş okura yarar. - Anlam listesi aynı **9** girdiyle **56/56** ve sessizlerin **39/39**'unu tarihlenebilir kılar; girdi başına tarihlenen iddia **1,889**'dan **6,222**'ye çıkar. - Fark girdi sayısında değil, girdiye yazılan **yanlışlanan iddia** alanındadır; bu bilgi değişiklik anında vardır ve yazılmazsa sonradan üretilemez. #### Sonraki Adım Bu ders okurun iki karşılıksız sorusundan birini kapattı. İkincisi duruyor ve ötekinden daha sık sorulur: **"bu neden çalışmıyor?"** Bu soruyla gelen okur ne bir konu adı bilir ne bir sürüm numarası; elinde yalnız bir belirti vardır — bir hata satırı, boş bir çıktı, beklenenden başka bir sonuç. Elindeki tek şey ürünün ona gösterdiğidir ve o gösterilen şey, dokümanın hiçbir bölüm başlığıyla eşleşmez. Sonraki ders belirtiden başlayan bir metnin kapsadığı okur sorusuyla kavramdan başlayanın kapsadığını karşılaştırır ve sorun giderme içeriğinin ulaşamadığı sınırı adlandırır. ### Sorun Giderme İçeriği Source: https://academia.sh/tr/kurslar/teknik-yazarlik/sorun-giderme-icerigi Belirtiyle gelen okur kavramdan başlayan metnin 17 arızanın yalnız 8'ine ulaşır ve 51 kararın 8'ini karşılar (0,1569); belirti–neden–çözüm düzeni 17'sine birden ulaşıp 51'ini karşılar, ama sessiz bayatlayan 39 iddia hiç belirti üretmediği için sorun gidermenin de dışında kalır. Önceki ders okurun iki karşılıksız sorusundan birini kapattı: sürüm notu, bayat bir iddianın ne zaman düştüğünü tarihlenebilir kıldı. İkincisi duruyor ve ötekinden çok daha sık sorulur: **"bu neden çalışmıyor?"** Bu soruyla gelen okurun elinde bir konu adı yoktur. Bir sürüm numarası da yoktur. Elinde yalnız ürünün ona gösterdiği bir **belirti** vardır: bir hata satırı, boş bir çıktı, beklenenden başka bir sonuç. Bu ders o belirtiden başlayan bir metnin ne kadarını karşıladığını, kavramdan başlayan bir metnin ise ne kadarını karşıladığını ölçer. #### Belirtiyle Gelen Okur Dört türün ve sürüm notunun ortak bir varsayımı vardı: okur ne aradığını **adlandırabilir**. Öğreticiye gelen "başlamak istiyorum" der, referansa gelen "şu alanın tipi" der, sürüm notuna gelen "altıncı sürümde ne oldu" der. Beş metnin beşi de bir ad üzerinden indekslenir. Arızayla gelen okur bunu yapamaz. Gördüğü şey bir ad değil, bir **sonuçtur** — ve o sonucun hangi kavrama ait olduğunu bilseydi zaten arızayı çözmüş olurdu. Uyuşmazlık buradadır: **dokümanın indeksi kavramdır, okurun indeksi belirtidir.** İki indeks arasındaki çeviriyi okurun yapması beklenir ve okur tam olarak o çeviriyi yapamadığı için oradadır. Sorun giderme içeriği, indeksi çeviren metindir. Ayrı bir tür olmasının nedeni farklı bilgi taşıması değil — taşıdığı bilginin çoğu zaten açıklamada ve referansta vardır. Ayrı olmasının nedeni **farklı indekslenmesidir**: girişleri belirtiden başlar. #### Belirti, Neden, Çözüm Sorun giderme girişinin üç bölümü vardır ve üçü okurun üç ayrı gereksinimini karşılar. ```text # kurgu ürünün sorun giderme bölümünden bir giriş # örnek metin, çalıştırılmamıştır belirti `istasyon baslat` komutu şunu yazıp çıkıyor: "bilinmeyen seçenek: --aralik" neden Örnekleme aralığı artık çağrı seçeneğiyle değil, profil alanıyla veriliyor; eski seçenek kaldırıldı. çözüm Aralık, profil dosyasındaki `ornekleme` alanına yazılır ve komut seçeneksiz çalıştırılır. ``` **Belirti** okurun **tanıma** gereksinimini karşılar: gördüğü şey bilinen bir arıza mı, yoksa kendi kurulumundaki bir tuhaflık mı? Bu, sanıldığından önemli bir yanıttır; okurun saatlerini yiyen şey çoğu zaman arızanın kendisi değil, arızanın tanınıp tanınmadığını bilmemesidir. **Neden** okurun **neden** gereksinimini karşılar. **Çözüm** okurun **eylem** gereksinimini karşılar. Belirti bölümünün yazımı bu üçünün en zorudur, çünkü **okurun gördüğü biçimde** yazılmak zorundadır. "Aralık seçeneği kaldırıldı" bir belirti değil, bir nedendir; okur arama kutusuna onu yazmaz. Okurun yazacağı şey ekranda gördüğü satırdır. Sorun giderme içeriğinin en sık kaçırdığı nokta budur: giriş, doğru bilgiyi okurun aramayacağı bir adla başlıklandırır ve bulunmaz. #### Kavramdan Başlamanın Bedeli Aynı bilginin kavramdan başlayan bir sürümü de vardır ve genellikle zaten yazılmıştır: açıklama metni örnekleme aralığının ne olduğunu ve nereden verildiğini anlatır. Okur o metne ulaşabilseydi arızayı çözerdi. Ulaşabilmesi bir koşula bağlıdır: **arızanın kendisinin, değişen şeyi adlandırması.** "bilinmeyen seçenek: --aralik" satırı adlandırır — okur `--aralik` dizgisini alır, dokümanda arar ve açıklamaya düşer. Ama her arıza böyle konuşmaz. Adımların sırası değiştiğinde çıkan şey bir ad değil, bir yokluktur: komut çalışır, hata vermez, beklenen sonucu üretmez. Okurun elinde arayacak bir dizgi yoktur ve kavram indeksine giremez. Ölçüm bu ayrımı sayar. İmza ve ad yüzeylerine bağlı arızalar kendini adlandırır; akış yüzeyine bağlı olanlar adlandırmaz. Ölçümün varsayımları: - **DT47** — Ölçülen küme kursun kurgu kümesidir: **56** iddia, dört tür, dört yüzey, **17** gömülü örnek. Karışım ve yüzey sıklıkları değiştirilmez. - **DT48** — Ölçüm **on ikinci sürümde** yapılır; orada iddiaların tamamı bayattır ve sorun giderme içeriğinin ulaşabileceği en geniş küme oluşur. - **DT49** — Bir **belirti**, ancak çalıştırılabilir örneğe gömülü bir iddia bayatlayınca doğar. Gömülü olmayan bir iddia yanlışlandığında ürün hiçbir şey göstermez. - **DT50** — Her belirti tek bir sorun giderme girişine karşılık gelir; iki iddianın aynı belirtiyi vermesi bu ölçümde yoktur. - **DT51** — Okurun bir arıza karşısında üç gereksinimi vardır: **tanıma**, **neden**, **eylem**. Bunlar kursun altı okur sorusundan ayrıdır ve tek bir arızanın içindedir. - **DT52** — **Kavramdan başlayan** metin kavram üzerinden indekslenir; okur ancak arıza değişen şeyi **adlandırıyorsa** girişe ulaşır. - **DT53** — **İmza** ve **ad** yüzeylerine bağlı arızalar kendini adlandırır (eksik alan, bilinmeyen seçenek, bulunamayan kod); **akış** yüzeyine bağlı olanlar adlandırmaz. - **DT54** — **Belirtiden başlayan** metin belirti üzerinden indekslenir; okur belirtiyi zaten elinde tuttuğu için girişlerin tamamına ulaşır. - **DT55** — Ulaşılan bir giriş, yalnız **taşıdığı bölümlerin** karşıladığı gereksinimleri kapatır; taşımadığı bölüm okuru başka bir metne gönderir ve bu ölçümde karşılanmamış sayılır. - **DT56** — Kavramdan başlayan metin yalnız **neden** bölümünü taşır; açıklamanın işi eylem vermek değildir ve bu bir kusur olarak değil, tür tanımı olarak alınır. - **DT57** — Karar ölçeği **belirti sayısı × gereksinim sayısıdır**; her belirtinin her gereksinimi ayrı bir karardır. - **DT58** — Kümenin çözünürlüğü iddia ölçeğinde **1/56**, karar ölçeğinde **1/51**'dir. #### Ölçüm ```python """Sorun giderme icerigi: belirtiden baslayan metin ile kavramdan baslayan. Bolum 1 - bayat iddialarin kaci belirti uretiyor, kaci hic uretmiyor. Bolum 2 - uc metin duzeninin ulastigi belirti ve karsiladigi okur gereksinimi. """ 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} SURUM = 12 # Arizanin kendisi degisen seyi adlandiriyor mu: okur kavrami buradan bulur. KENDINI_ADLANDIRAN = {"imza", "ad"} # Okurun bir ariza karsisindaki uc gereksinimi. GEREKSINIM = ("tanıma", "neden", "eylem") # Metin duzeni -> (indeks, tasidigi bolumlerin karsiladigi gereksinimler). DUZENLER = { "kavramdan başlayan": ("kavram", ("neden",)), "belirtiden başlayan (belirti–çözüm)": ("belirti", ("tanıma", "eylem")), "belirtiden başlayan (belirti–neden–çözüm)": ("belirti", ("tanıma", "neden", "eylem")), } def iddialar(): liste, no = [], 0 for tur, dagilim in TURLER.items(): gomulu_hedef = 0 for yuzey, adet in dagilim.items(): for _ in range(adet): no += 1 gomulu_hedef += ORNEKLI[tur] gomulu = gomulu_hedef >= 1 and yuzey != "kavram" if gomulu: gomulu_hedef -= 1 liste.append({"no": no, "tur": tur, "yuzey": yuzey, "gomulu": gomulu}) return liste L = iddialar() bayat = [i for i in L if SURUM // SIKLIK[i["yuzey"]] >= 1] # Belirti ancak calistirilabilir ornege gomulu bir iddia bayatlayinca dogar. belirtili = [i for i in bayat if i["gomulu"]] sessiz = [i for i in bayat if not i["gomulu"]] print(f"sürüm {SURUM} | iddia {len(L)} | bayat {len(bayat)} | " f"belirti üreten {len(belirtili)} | belirti üretmeyen {len(sessiz)}") print() print(f"{'yüzey':<8s} {'bayat':>5s} {'belirti':>7s} {'belirtisiz':>10s} " f"{'arıza kendini adlandırıyor':>26s}") for y in SIKLIK: g = [i for i in bayat if i["yuzey"] == y] b = [i for i in g if i["gomulu"]] print(f"{y:<8s} {len(g):5d} {len(b):7d} {len(g) - len(b):10d} " f"{('evet' if y in KENDINI_ADLANDIRAN else 'hayır'):>26s}") print() toplam = len(belirtili) * len(GEREKSINIM) print(f"belirti {len(belirtili)} | gereksinim {len(GEREKSINIM)} | " f"karar {toplam}") print() print(f"{'metin düzeni':<42s} {'ulaşılan':>8s} {'karşılanan':>10s} " f"{'oran':>6s}") for ad, (indeks, bolumler) in DUZENLER.items(): ulasilan = [i for i in belirtili if indeks == "belirti" or i["yuzey"] in KENDINI_ADLANDIRAN] karsilanan = len(ulasilan) * len(bolumler) print(f"{ad:<42s} {len(ulasilan):8d} {karsilanan:10d} " f"{karsilanan / toplam:6.4f}") print() # Alti okur sorusu: iki tur eklendikten sonra kac soru bir metne dusuyor. SORULAR = { "nereden başlarım": "öğretici", "şunu nasıl yaparım": "nasıl yapılır", "bu neden böyle": "açıklama", "bu alanın tipi ne": "referans", "hangi sürümde değişti": "sürüm notu", "bu neden çalışmıyor": "sorun giderme", } print("okur sorusu -> karşılayan metin") for s, t in SORULAR.items(): print(f" {s:<22s} {t}") print(f"soru {len(SORULAR)} | karşılanan " f"{sum(1 for t in SORULAR.values() if t)} | karşılanmayan " f"{sum(1 for t in SORULAR.values() if not t)}") print(f"sorun gidermenin kapsayabildiği iddia {len(belirtili)}/{len(L)} " f"({len(belirtili) / len(L):.4f}) | erişemediği bayat iddia " f"{len(sessiz)}") ``` ``` sürüm 12 | iddia 56 | bayat 56 | belirti üreten 17 | belirti üretmeyen 39 yüzey bayat belirti belirtisiz arıza kendini adlandırıyor imza 22 5 17 evet akis 16 9 7 hayır ad 7 3 4 evet kavram 11 0 11 hayır belirti 17 | gereksinim 3 | karar 51 metin düzeni ulaşılan karşılanan oran kavramdan başlayan 8 8 0.1569 belirtiden başlayan (belirti–çözüm) 17 34 0.6667 belirtiden başlayan (belirti–neden–çözüm) 17 51 1.0000 okur sorusu -> karşılayan metin nereden başlarım öğretici şunu nasıl yaparım nasıl yapılır bu neden böyle açıklama bu alanın tipi ne referans hangi sürümde değişti sürüm notu bu neden çalışmıyor sorun giderme soru 6 | karşılanan 6 | karşılanmayan 0 sorun gidermenin kapsayabildiği iddia 17/56 (0.3036) | erişemediği bayat iddia 39 ``` #### Kapsamın Okunması Orta tablo dersin ana karşılaştırmasını veriyor. On yedi arıza ve üç gereksinim **51** karar eder. **Kavramdan başlayan** metin on yedi arızanın yalnız **8**'ine ulaşıyor ve **8** karar karşılıyor: oran **0,1569**. İki ayrı kayıp üst üste biniyor. Birincisi ulaşılabilirlik: akış yüzeyine bağlı dokuz arıza kendini adlandırmıyor, okurun arayacağı bir dizgi yok ve o dokuz giriş hiç bulunamıyor. İkincisi kapsam: ulaşılan sekiz girişte bile yalnız **neden** bölümü var; okur nedeni öğreniyor, ne yapacağını öğrenmiyor. **Belirti–çözüm** düzeni on yedisine birden ulaşıyor ve **34** karar karşılıyor: **0,6667**. Sıçrama tek bir değişiklikten geliyor — indeksin değişmesinden. İçerik aynı; girişlerin başlığı değişti. Bu, kurs boyunca ölçülen en ucuz kazançtır: yeni bir cümle yazılmadan karşılanan karar sayısı dört katından fazlasına çıkıyor. **Belirti–neden–çözüm** düzeni **51/51** ile kümeyi kapatıyor: **1,0000**. Aradaki fark **17** karardır ve tamamı **neden** bölümünden gelir. Neden bölümü olmayan bir sorun giderme metni çalışır ama okuru öğretmez: aynı okur benzer bir arızada yine gelir, çünkü neyin değiştiğini hiç öğrenmemiştir. Sıralamanın kendisi de bir sonuç veriyor. Kavramdan başlayan metin **0,1569**, belirtiden başlayan en yalın hâliyle **0,6667**. Aradaki dört katı aşan fark, daha iyi yazmaktan değil, **metnin okurun elindeki şeyle indekslenmesinden** geliyor. Aynı bilgi, iki ayrı başlıkla, iki ayrı sonuç. #### Taksonominin Tamamlanması ve Sınırı Son blok ilk bakışta kursun kapanışı gibi duruyor: altı okur sorusunun **6**'sı bir metne düşüyor, karşılanmayan **0**. İkinci ders taksonominin sınırını iki soruyla çizmişti; beşinci ders birini, bu ders ötekini kapattı. Okurun getirebileceği hiçbir soru artık ortada kalmıyor. Ama üst tablo bu rahatlığı bozuyor. On ikinci sürümde **56** iddianın **56**'sı bayat ve bunların yalnız **17**'si belirti üretiyor. Sorun giderme içeriğinin kapsayabileceği en geniş küme **17/56** — **0,3036**. Kalan **39** iddia hiçbir belirti üretmiyor, dolayısıyla hiçbir sorun giderme girişi yazılamıyor. Yazacak kişi neyi yazacağını bilmiyor; okur da neyi soracağını. Yüzey kırılımı bunu daha da keskinleştiriyor. İmza yüzeyinde **22** bayat iddianın **17**'si belirtisiz; kavram yüzeyinde **11** bayat iddianın **11**'i belirtisiz. Sorun gidermenin en iyi kapsadığı yüzey **akış**: on altı bayat iddianın **9**'u belirti veriyor. Ama akış aynı zamanda kendini **adlandırmayan** yüzeydir — yani sorun gidermenin en çok girişi olduğu yerde kavram indeksi tümüyle işe yaramaz. İki tablo birbirini tam olarak buradan tamamlıyor. Kursun bu konusunun bıraktığı sonuç şudur: **altı soru da bir metne düşer, ama metinlerin hepsi birlikte bile bayat iddiaların yalnız 17'sine ulaşır.** Taksonomi tamamlandı; kapsam tamamlanmadı. Sessiz bayatlamayı görünür kılan tek şey, bu konu boyunca yalnız iki yerde belirdi — çalıştırılabilir örneğe gömülü olmak ve sürüm notunun anlam listesine yazılmak. Kalanı ancak biri arayarak bulur. #### Girişin Kendisi de Bayatlar Sorun giderme içeriği bu konudaki metinler arasında tuhaf bir yerde durur: **var olma gerekçesi bir arızadır ve arıza giderilebilir.** Öteki türler ürün yaşadığı sürece geçerli kalmayı hedefler; bir sorun giderme girişi ise, işaret ettiği arıza düzeltildiği anda gereksizleşir. Gereksiz hâle gelmek zararsız görünür, değildir. Kalan bir giriş okura artık oluşmayan bir belirtiyi tanıtır ve olmayan bir nedene bağlar. Okur benzer ama başka bir arızayla gelir, belirtinin yakın bir satırını görür, girişe ulaşır ve **yanlış nedene** ikna olur. Bu, boş bir sonuç değil, yanlış bir sonuçtur — hiç yazılmamış olmasından kötüdür. Bu tür girişler kursun ölçüsünde özel bir yerdedir. Bayat bir sorun giderme girişi **sessizdir**, çünkü hiçbir şey kırmaz: metin okunur, adımlar uygulanır, arıza geçmez ve okur kendi yaptığından şüphelenir. Belirtiyi ilk gördüğü metnin yanlış olabileceği aklına gelmez, çünkü o metin tam olarak onun gördüğü satırla başlamaktadır. Buradan pratik bir kural çıkar ve bu konunun tek bakım kuralıdır: bir sorun giderme girişi yazılırken **hangi sürümde geçerli olduğu** yazılmalıdır. Üçüncü dersteki aşılmış kayıt ile aynı düzenek — bir iddianın kapsamını yazmak, onu yanlışlıktan çıkarıp tarihe taşır. #### Özet - Belirtiyle gelen okurun indeksi dokümanın indeksine uymaz: doküman kavramla, okur belirtiyle indeksler. Sorun giderme içeriği bu çeviriyi yapan metindir. - Girişin üç bölümü okurun üç gereksinimini karşılar: **belirti** tanımayı, **neden** nedeni, **çözüm** eylemi. Belirti, okurun **gördüğü** biçimde yazılmak zorundadır. - On yedi arıza ve üç gereksinim **51** karar eder; kavramdan başlayan metin **8**'ini karşılar (**0,1569**), belirti–çözüm **34**'ünü (**0,6667**), belirti–neden–çözüm **51**'ini (**1,0000**). - Kavramdan başlayan metin on yedi arızanın yalnız **8**'ine ulaşır: akış yüzeyine bağlı dokuz arıza kendini adlandırmaz ve kavram indeksine hiç giremez. - Sorun gidermenin kapsayabildiği en geniş küme **17/56**'dır (**0,3036**); sessiz bayatlayan **39** iddia hiç belirti üretmediği için bu türün de dışında kalır. - Altı okur sorusunun **6**'sı artık bir metne düşer — taksonomi tamamlandı, kapsam tamamlanmadı. #### Sonraki Adım Bu konu boyunca metinler okurun **sorusuna** göre ayrıldı ve ölçüldü; altı sorunun altısı da artık bir türe düşüyor. Ama her ölçümde sessizce kabul edilen bir şey vardı: okurun kim olduğu. "Yeni okur", "bakım yapan", "koda dokunacak kişi" — bu roller derslerin içinde geçti, hiçbir dokümanın içinde geçmedi. Peki bir metin okurunun kim olduğunu yazmıyorsa ne olur? Sonraki konu buradan başlar ve ilk dersi tam bu soruyu ölçer: yazılmamış bir ön bilgi varsayımı, doğru kalan iddiaların kaçını okunamaz kılar? Bir cümlenin hâlâ doğru olması, onu okuyabilecek birinin var olduğu anlamına gelmiyor. ## Yazım Disiplini Ön bilgi varsayımlarının açık yazımı, taranabilir metin kurma, terim tutarlılığı ve ses birliği, çalışır ve doğrulanabilir örnekler, ve diyagramın metne hizmet etmesi. ### Okur Tanımı Source: https://academia.sh/tr/kurslar/teknik-yazarlik/okur-tanimi Yazılmamış ön bilgi varsayımı iddiayı yanlış yapmaz, okunamaz yapar; üçüncü sürümde hâlâ doğru olan 18 iddianın yeni okur için okunabilir olanı okur tanımı yokken 3, tam yazılmışken 18'dir. Önceki ders taksonominin son boşluğunu kapattı: sürüm notu ve sorun giderme içeriğiyle birlikte altı okur sorusunun **hepsi** artık bir türe düşüyor. Doküman hangi sorunun hangi türde yanıtlandığını biliyor. Bir tür soruyu ancak okur cümleyi çözebiliyorsa yanıtlar. Cümlenin doğru olması yetmez; cümlenin varsaydığı ön bilgi okurda yoksa ve doküman o varsayımı yazmamışsa, cümle okur için bir yanıt değil bir duvardır. Bu dersin sorusu şudur: **yazılmamış bir ön bilgi varsayımı kaç iddiayı okunamaz kılar?** #### Okurun Kim Olduğu Yazılmamış Bir Karardır Her teknik metin birisi için yazılır. Yazan, yazarken zihninde bir okur taşır: neyi bildiği, neyi kurmuş olduğu, hangi terimi tanıdığı. Bu tablo bir varsayımlar kümesidir ve **her zaman vardır**. Yazmak onu var etmez, yalnız görünür kılar. Yazmamak onu ortadan kaldırmaz, yalnız tartışılamaz kılar. Yazılmamış varsayım belirli bir biçimde başarısız olur. Okur cümleye gelir, çözemez ve **neden çözemediğini bilemez**. Bilmesi gereken bir terim miydi, yoksa dokümanın tanımlaması gereken bir terim mi? Bu ayrımı yapamayan okur ya metni bırakır ya da yanlış yerde arar. Maliyet bilgisizliğin kendisi değil, bilgisizliğin **adlandırılmamış** olmasıdır. Yazılı varsayım okuru bilgili yapmaz. Yaptığı tek şey duvarı bir tabelaya çevirmektir: bu metin şunu bildiğini varsayar. Okur o eksiği kapatmayı seçebilir, başka bir kaynağa gidebilir ya da metnin kendisi için olmadığına karar verebilir. Üçü de bir karardır; duvarda karar yoktur. #### İki Ayrı Eksen Kurs buraya kadar tek eksen ölçtü: bir iddia **hâlâ doğru mu**. Bu dersin eklediği ikinci eksen **okunabilirlik**: okur o cümleyi çözebiliyor mu. İki eksen bağımsızdır ve dört bileşim üretir. **Doğru ve okunabilir** olan iddia dokümanın gerçek sermayesidir; okurun sorusunu kapatır. **Doğru ama okunamaz** olan iddia boşa yazılmış emektir: cümle doğrudur, kimse ondan yararlanamaz. **Bayat ve okunabilir** olan iddia en zararlısıdır; okur onu anlar, uygular ve yanılır. **Bayat ve okunamaz** olan iddia zarar da vermez, işe de yaramaz. Bu ayrım bir ölçüm sonucudur, bir sınıflandırma tercihi değil. Aynı 56 iddia iki eksende ayrı ayrı sayılabilir ve iki sayının birbirini takip etmediği görülebilir. Ön bilgi varsayımını yazmak bir iddianın **bayatlamasını geciktirmez**; onu okunabilir yapar. Yüzey sıklığı değişmediği için bayat sayısı üç rejimde de aynı kalır. #### Okur Tanımı Ne Yazar Ölçülebilir bir okur tanımı dört şeyi yazar: okurun **rolü**, bilindiği varsayılan ön bilgiler, kapsam dışında bırakılanlar ve metnin sonunda okurun yapabilecek olduğu şey. Rol kişi değildir; bir kişi gün içinde iki rolde de okuyabilir. ```text # ornek dokuman parcasi , calistirilmamistir zayıf okur tanımı Bu belge, ürünü kullanmak isteyen herkes içindir. açık okur tanımı Rol: kurulumu yapılmış bir kurgu ürünü ilk kez çalıştıran okur. Bilindiği varsayılan: komut satırında dizin değiştirme ve dosya okuma. Bilinmediği varsayılan: ürünün veri modeli, kimlik düzeni, eşzamanlı çalışma. Kapsam dışı: dağıtım ve ölçekleme. Metnin sonunda okur: tek bir ölçümü çalıştırıp çıktısını okuyabilir. ``` İki tanım arasındaki fark üslup değildir. Birincisinden hiçbir iddia hakkında karar çıkarılamaz: "herkes" kümesi hiçbir ön bilgiyi dışarıda bırakmaz, dolayısıyla hiçbir cümle "bu okur için fazla" ya da "bu okur için eksik" diye işaretlenemez. İkincisi her iddia için bir eşleştirme yapılmasına izin verir: iddianın istediği ön bilgi listede var mı, yok mu. **Okur tanımının ölçülebilirliği, dokümanın denetlenebilirliğinin ön koşuludur.** Kapsam dışı satırı özellikle önemlidir çünkü tek başına bir soruyu kapatır. Dağıtımı arayan okur ilk on satırda aradığının burada olmadığını öğrenir ve metni okumadan bırakır. Bu bir kayıp değil, doğru bir yönlendirmedir. Ölçümün varsayımları: - **YD1** — 56 iddia ortak kurgudan gelir: dört tür, dört yüzey ve **17** çalıştırılabilir örneğe gömülü iddia. Kâhin kurgunun kendisidir; hangi iddianın hangi yüzeye bağlı olduğunu ve hangi ön bilgiyi istediğini biz yazdığımız için biliriz. - **YD2** — Her iddia bir ya da iki ön bilgi ister; ön bilgiler beş başlıktan seçilir. Dağılım kurgudan üretilir ve iddianın **türüne bakmaz** — ön bilgi bir yüzey değildir. - **YD3** — Üç okur rolü ölçülür: yeni okur beş ön bilgiden birini bilir, uygulayan üçünü, bakım yapan beşini. Rol kişi değildir, bir okuma durumudur. - **YD4** — Bir iddia, istediği ön bilgilerin hepsi ya okurda ya da okur tanımında yazılıysa **okunabilir** sayılır. Yazılı varsayım okuru bilgili yapmaz; eksiği adlandırır ve okur onu kapatabilir. Ölçüm bu adlandırmayı okunabilirlik sayar. - **YD5** — Üç okur tanımı rejimi denenir: **yok** (hiçbir varsayım yazılı değil), **kısmi** (iki varsayım yazılı), **tam** (beşi de yazılı). - **YD6** — Okunabilirlik bayatlamayı değiştirmez. Bir iddianın bayat olup olmadığı yalnız bağlandığı yüzeye ve sürüme bakar; okur tanımı bu hesaba girmez. #### Ölçüm ```python """Okur tanimi: yazilmamis on bilgi varsayimi kac iddiayi okunamaz kiliyor. Bolum 1 - on bilginin iddialara dagilimi. Bolum 2 - uc okur rolu ve uc okur tanimi rejimi. Bolum 3 - ucuncu surumde dogru/bayat/sessiz ile okunabilirligin kesismesi. """ TOHUM = 20260816 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} ONBILGI = ("kurulum", "komut satırı", "veri modeli", "kimlik", "eşzamanlılık") ROLLER = {"yeni okur": {"komut satırı"}, "uygulayan": {"komut satırı", "kurulum", "veri modeli"}, "bakım yapan": set(ONBILGI)} TANIM = {"yok": set(), "kısmi": {"kurulum", "komut satırı"}, "tam": set(ONBILGI)} def uretec(tohum): d = tohum % 2147483646 + 1 def r(n): nonlocal d d = (d * 48271) % 2147483647 return d % n return r 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 onbilgi_ata(liste, tohum=TOHUM): """Bu dersin eklediği tek şey: her iddianın gerektirdiği ön bilgi.""" r = uretec(tohum) for i in liste: gerek, adet = set(), 2 if r(4) == 0 else 1 while len(gerek) < adet: gerek.add(ONBILGI[r(len(ONBILGI))]) i["onbilgi"] = gerek return liste def bayat_mi(i, surum): return surum // SIKLIK[i["yuzey"]] >= 1 def okunabilir(i, rol, yazili): """Okurun bilmediği ve dokümanın yazmadığı ön bilgi iddiayı okunamaz kılar.""" return not (i["onbilgi"] - ROLLER[rol] - yazili) A = onbilgi_ata(iddialar()) print(f"iddia {len(A)} | örneğe gömülü {sum(i['gomulu'] for i in A)} | " f"iki ön bilgi isteyen {sum(len(i['onbilgi']) == 2 for i in A)}") print("ön bilgi " + " ".join(f"{o} {sum(o in i['onbilgi'] for i in A)}" for o in ONBILGI)) print() print(f"{'okur rolü':>12s}" + "".join(f" {'tanım ' + t:>12s}" for t in TANIM)) for rol in ROLLER: satir = f"{rol:>12s}" for t, yazili in TANIM.items(): satir += f" {sum(okunabilir(i, rol, yazili) for i in A):12d}" print(satir) print() kapali = sum(okunabilir(i, "yeni okur", set()) for i in A) print("yeni okur için tek başına yazılan ön bilgi açılan iddia") for o in ONBILGI: acik = sum(okunabilir(i, "yeni okur", {o}) for i in A) print(f" {o:40s} {acik - kapali:6d}") print() print("sürüm 3, yeni okur doğru+okunabilir doğru ama okunamaz bayat sessiz") for t, yazili in TANIM.items(): dogru = [i for i in A if not bayat_mi(i, 3)] bayat = [i for i in A if bayat_mi(i, 3)] sessiz = [i for i in bayat if not i["gomulu"]] okur = sum(okunabilir(i, "yeni okur", yazili) for i in dogru) print(f" tanım {t:12s} {okur:14d} {len(dogru) - okur:20d}" f" {len(bayat):6d} {len(sessiz):7d}") ``` ``` iddia 56 | örneğe gömülü 17 | iki ön bilgi isteyen 13 ön bilgi kurulum 16 komut satırı 11 veri modeli 10 kimlik 13 eşzamanlılık 19 okur rolü tanım yok tanım kısmi tanım tam yeni okur 5 19 56 uygulayan 27 27 56 bakım yapan 56 56 56 yeni okur için tek başına yazılan ön bilgi açılan iddia kurulum 14 komut satırı 0 veri modeli 7 kimlik 9 eşzamanlılık 14 sürüm 3, yeni okur doğru+okunabilir doğru ama okunamaz bayat sessiz tanım yok 3 15 38 24 tanım kısmi 7 11 38 24 tanım tam 18 0 38 24 ``` #### Rolün Ödettiği İkinci tablo üç rolü yan yana koyuyor ve aradaki fark bir üslup farkı değil, bir büyüklük farkı. Okur tanımı yokken **yeni okur 56 iddianın 5'ini** okuyabiliyor. Aynı dokümandan **bakım yapan 56'sını** okuyor. İki okur aynı metne bakıyor ve biri onda birini alıyor. Bu tablo yazarın en sık yaptığı hatayı sayıya çeviriyor: yazan kişi neredeyse her zaman **bakım yapan** rolündedir. Ürünü bilir, kurulumu yapmıştır, veri modelini tasarlamıştır. Kendi rolünden baktığında dokümanın **56/56** verdiğini görür ve metni yeterli bulur. Yeni okur için sayı **5**'tir ve bu farkı yazan kendi başına göremez, çünkü eksik ön bilgi yazanda yoktur. Ortadaki rol de öğreticidir. **Uygulayan** rolü kısmi tanımdan hiç yararlanmıyor: **27** ile **27** aynı. Kısmi tanımın yazdığı iki varsayımı uygulayan zaten biliyor. **Okur tanımı, en az bilen role göre yazılmazsa hiçbir şey açmaz.** Yazılan satırın değeri, doğruluğuyla değil, hangi okurun eksiğini adlandırdığıyla ölçülür. #### Bir Doküman Kaç Rolü Taşır Tablo bir soruyu doğrudan doğuruyor: aynı doküman hem yeni okuru hem bakım yapanı taşıyabilir mi? Sayılar taşıyamayacağını söylüyor. Yeni okura göre yazılmış bir metin, bakım yapanın zaten bildiği ön bilgileri satır satır tekrarlar; bakım yapana göre yazılmış bir metin yeni okura **5/56** verir. Ortada tek bir metnin ikisini birden karşıladığı bir ayar yoktur, çünkü açılan iddia sayısı ile tekrarlanan satır sayısı ters yönde hareket eder. Kursun ilk konusu dört türü ayrı okur durumlarına yazılmış olarak kurmuştu; eşlemeyi role bağlayan bu derstir. Öğretici **yeni okur** rolüne, nasıl yapılır **uygulayan** rolüne, referans **bakım yapan** rolüne yazılır; açıklama üçünü de okurlar ama farklı derinlikte. Öyleyse okur tanımı dokümanın tamamına değil, **her türe ayrı ayrı** yazılır ve her tür kendi rolünü ilan eder. Bunun ölçülebilir sonucu şudur: bir metinde okunamaz iddia sayısı yüksekse iki ayrı kusurdan biri vardır. Ya okur tanımı eksiktir — o zaman çözüm birkaç satır yazmaktır. Ya da metin yanlış türdedir: referans olarak yazılmış bir metin öğretici gibi okunmaktadır ve çözüm yazmak değil, **ayırmaktır**. Okur tanımı bu iki kusuru birbirinden ayırt etmenin tek yoludur; tanım yazılmadan hangi kusurun bulunduğu bilinemez. #### En Pahalı Yazılmamış Varsayım Üçüncü tablo tek tek varsayımların ağırlığını veriyor. Yeni okur için **eşzamanlılık** ve **kurulum** varsayımlarının her biri tek başına **14** iddia açıyor; **kimlik** 9, **veri modeli** 7 açıyor. **Komut satırı** ise **0** açıyor — çünkü onu yeni okur zaten biliyor ve yazmak bir şey eklemiyor. Sayılar toplanmıyor: 14 + 0 + 7 + 9 + 14 toplamı 44, oysa tam tanım 5'ten 56'ya, yani **51** iddia açıyor. Aradaki fark iki ön bilgi isteyen **13** iddiadan geliyor; onlar ancak iki varsayım birden yazıldığında açılıyor. Bu, okur tanımının **parça parça yazılmasının** neden beklenenden az kazandırdığını açıklıyor. Pratik sonuç şudur: okur tanımı yazılırken sıralama önemlidir ve sıralamayı **açtığı iddia sayısı** belirler, yazma kolaylığı değil. Beş satırlık bir bölüm 51 iddia açıyorsa, o beş satır dokümanın en verimli beş satırıdır. Bu kümede ölçülebilen en küçük fark **1/56 = 0,0179**'dur. Tek tek varsayımların açtığı 7, 9 ve 14 iddia bu bandın çok üstündedir ve karşılaştırılabilir. Bir varsayımın diğerinden bir iddia fazla açması ise bu kümeyle savunulamaz; kurgu değişirse o sıra da değişir. #### Bayatlamayla Kesişme Son tablo iki ekseni birleştiriyor ve dersin en sıkı sonucu burada. Üçüncü sürümde dokümanın **38** iddiası bayat, **24**'ü **sessiz** bayat, geriye **18** doğru iddia kalıyor. Bu üç sayı üç rejimde de aynı: okur tanımı yazmak hiçbir iddianın ömrünü uzatmıyor. Yüzey sıklığı değişmedi, bayatlama da değişmedi. Değişen tek sütun okunabilirlik. Okur tanımı yokken, hayatta kalan **18** doğru iddianın yeni okur için okunabilir olanı **3**. Yani doküman üçüncü sürümde hâlâ doğru **18** cümle taşıyor ve yeni okur bunların **15**'ine erişemiyor. Tam tanımla aynı 18 cümlenin **18**'i okunabilir hâle geliyor. Bu iki sayının yan yana durması gerekiyor çünkü iki ayrı işi karıştırmayı engelliyor. Bayatlamayla savaşmak bir **bakım** işidir: yüzeyleri izlemek, denetim yapmak, üretilen içeriğe geçmek. Okunamazlıkla savaşmak bir **yazım** işidir ve **bir kere** yapılır: okur tanımı yazıldıktan sonra kavram yüzeyine bağlıdır ve yüzeylerin en yavaşı odur. Ürünün kavramları değişmedikçe okur tanımı doğru kalır; imzaya bağlı bir referans satırı iki sürümde bayatlarken okur tanımı on ikide bir yenilenir. #### Özet - Okurun kim olduğu her metinde bir varsayımdır; yazmak onu var etmez, **tartışılabilir** kılar. Yazılmamış varsayımın maliyeti okurun bilgisizliği değil, eksiğin adlandırılmamış olmasıdır. - Okunabilirlik ile bayatlama **bağımsız iki eksendir**: bir iddia doğru olduğu hâlde okunamaz, bayat olduğu hâlde okunabilir olabilir. En zararlı bileşim bayat ve okunabilir olandır. - Okur tanımı yokken yeni okur 56 iddianın **5**'ini, bakım yapan **56**'sını okur. Yazan kişi genellikle bakım yapan rolündedir ve bu farkı kendi başına göremez. - Kısmi tanım uygulayan rolüne hiçbir şey açmaz (**27** ile **27**); tek tek varsayımlar **14, 0, 7, 9, 14** iddia açar ve toplamları tam tanımın açtığı **51**'e ulaşmaz, çünkü **13** iddia iki varsayımı birden ister. - Üçüncü sürümde bayat **38**, sessiz **24**, doğru **18** sayıları üç rejimde de aynıdır; okur tanımı yalnız o 18 doğru iddianın kaçının okunabildiğini değiştirir: **3** ile **18**. #### Sonraki Adım Okur tanımı cümlenin çözülmesini sağlar; cümlenin **bulunmasını** sağlamaz. Tam tanımla yazılmış bir dokümanda yeni okur artık 56 iddianın hepsini okuyabilir, ama aradığı tek iddiaya ulaşmak için kaç satır taraması gerektiği hâlâ ölçülmedi. Sonraki ders başlık düzenine bakar: okurun sorusu ile onu yanıtlayan iddia arasındaki mesafe kaç adımdır, hangi başlıklandırma bu mesafeyi kısaltır ve başlığın kendisi hangi yüzeye bağlanır. ### Yapı ve Başlıklandırma Source: https://academia.sh/tr/kurslar/teknik-yazarlik/yapi-ve-basliklandirma Başlık düzeni okurun sorusuyla yanıtı arasındaki mesafeyi ölçer; otuz altı ziyarette başlıksız metin ortalama 26,38 adım isterken tür başlıklı 7,29, iki düzeyli 7,00 ister ve iki düzeyli düzen bu kazanç için altıncı sürümde 24 sessiz bayat başlık taşır. Önceki ders okur tanımını yazdı ve tam tanımla yeni okurun 56 iddianın hepsini çözebildiğini ölçtü. Çözebilmek erişebilmek değildir. Okur dokümanı baştan sona okumaz; gelirken bir sorusu vardır ve o soruyu yanıtlayan cümleyi arar. Bu dersin sorusu aramanın maliyetidir: **okurun sorusu ile onu yanıtlayan iddia arasında kaç adım vardır ve başlık düzeni bu mesafeyi ne kadar kısaltır?** İkinci bir soru da bununla birlikte gelir ve kursun eksenine bağlıdır: başlığın kendisi de bir cümledir, o hâlde o da bayatlar mı? #### Okur Okumaz, Tarar Teknik metnin okuru edebiyat metninin okuru değildir. Elinde bir iş vardır, o işin ortasında durmuştur ve metne bir soruyla gelir. Metni baştan okumaya karar vermesi ender bir durumdur; olağan olan **tarama**dır. Göz başlıktan başlığa atlar, bir tanesi soruya benzerse durur, altını okur, benzemiyorsa devam eder. **Taranabilir metin** bu davranışa göre kurulmuş metindir. Taranabilirliğin ölçüsü estetik değildir; okurun aradığı cümleye ulaşana kadar okumak zorunda kaldığı **birim sayısıdır**. Bu sayı ölçülebilir, çünkü hem başlıklar hem iddialar sayılabilir birimlerdir. Ölçünün tanımı şudur: bir başlığı okuyup "bu benim sorum değil" demek **bir adımdır**; bir iddiayı okuyup "bu benim yanıtım değil" demek de **bir adımdır**. İki iş de okurun dikkatini aynı ölçüde harcar. Bu eşitleme kaba görünebilir, ama başlıklandırmanın ne kazandırdığını görmenin tek yolu ikisini aynı birime çevirmektir. #### Bölümlendirmenin Ekseni Bir dokümanı bölümlere ayırmanın birden çok ekseni vardır ve seçilen eksen aramanın maliyetini belirler. Kursun ilk konusu bir ekseni zaten verdi: **tür**. İkinci bir eksen ürünün kendisinden gelir: **konu**. Üçüncü seçenek ikisini iç içe koymaktır. ```text # ornek baslik duzeni , calistirilmamistir tür başlıklı konu başlıklı tür + konu Öğretici Kurulum Öğretici Nasıl Yapılır Ölçüm Başlatma Kurulum Açıklama Çıktı Biçimi Ölçüm Başlatma Referans Yetki Çıktı Biçimi Hata ... Ayarlar Nasıl Yapılır Kurulum ... ``` Okur bu iki ekseni farklı güvenle kullanır. **Türü** sorunun biçiminden çıkarır: "nereden başlarım" diyen okur öğreticiyi arar, "bu alanın tipi ne" diyen referansı. **Konuyu** ise zaten bilir; okur işinin ortasındadır ve hangi konuda takıldığının farkındadır. İki eksen de okur için erişilebilir olduğu için ikisi de bölümlendirmeye elverişlidir. Bölümlendirmeme de bir seçimdir. Başlıksız metin tek bir akıştır ve okurun tek yolu baştan taramaktır. Ölçüm bu seçeneği de dördüncü satır olarak taşır, çünkü kıyas noktasıdır. Ölçümün varsayımları: - **YD11** — 56 iddia ortak kurgudan gelir: dört tür, dört yüzey, **17** çalıştırılabilir örneğe gömülü iddia. Kâhin kurgunun kendisidir. - **YD12** — Bu dersin eklediği tek şey her iddianın **konusudur**; konu altı başlıktan kurgu üreticiyle seçilir ve iddianın türüne bakmaz. - **YD13** — Okur ziyareti bir **soru–konu** çiftidir. Altı okur sorusu ile altı konunun bütün bileşimleri denenir: **36 ziyaret**. Sorular ortak tanımdan gelir ve ikisi hiçbir türe düşmez. - **YD14** — Bir başlığı okumak bir adımdır, bir iddiayı okumak bir adımdır. Okur eşleşen başlığa gelene kadar başlıkları **sırayla** okur; eşleşen bölümün iddialarını da sırayla okur. - **YD15** — Okur türü sorusundan, konuyu kendi durumundan doğru çıkarır. Ölçüm bir anlama ölçümü değil, bir **mesafe** ölçümüdür. - **YD16** — Yanıt bulunamazsa okur bütün başlıkları ve bütün iddiaları taramış sayılır; bulunamayan ziyaretin maliyeti düzenin toplam birim sayısıdır. - **YD17** — Başlığın kendisi bir iddiadır ve bir yüzeye bağlanır: tür adları **kavrama**, konu adları **ada**. Başlık çalıştırılabilir örneğe gömülemez; bu yüzden bayatlayan her başlık **sessizdir**. #### Ölçüm ```python """Baslik duzeni: okurun sorusuna kac adimda ulasiliyor. Bolum 1 - iddialarin konulara dagilimi ve 36 okur ziyareti. Bolum 2 - dort baslik duzeninde adim sayisi ve bulunamayanin ayrimi. Bolum 3 - baslik da bir iddiadir: baslik kumesinin dogru/bayat/sessiz tablosu. """ TOHUM = 20260816 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} SORULAR = {"nereden başlarım": "öğretici", "şunu nasıl yaparım": "nasıl yapılır", "bu neden böyle": "açıklama", "bu alanın tipi ne": "referans", "hangi sürümde değişti": None, "bu neden çalışmıyor": None} KONULAR = ("kurulum", "ölçüm başlatma", "çıktı biçimi", "yetki", "hata", "ayarlar") SURUMLER = (0, 1, 2, 3, 6, 12) # Başlığın kendisi de bir iddiadır ve bağlandığı yüzeye göre bayatlar. BASLIK = {"başlıksız": {}, "tür başlıklı": {"kavram": 4}, "konu başlıklı": {"ad": 6}, "tür + konu": {"kavram": 4, "ad": 24}} def uretec(tohum): d = tohum % 2147483646 + 1 def r(n): nonlocal d d = (d * 48271) % 2147483647 return d % n return r 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 konu_ata(liste, tohum=TOHUM): """Bu dersin eklediği tek şey: her iddianın konusu.""" r = uretec(tohum) for i in liste: i["konu"] = KONULAR[r(len(KONULAR))] return liste def bayat_mi(yuzey, surum): return surum // SIKLIK[yuzey] >= 1 A = konu_ata(iddialar()) ZIYARET = [(s, k) for s in SORULAR for k in KONULAR] BOLUM = {"başlıksız": ([None], [None]), "tür başlıklı": (list(TURLER), [None]), "konu başlıklı": ([None], list(KONULAR)), "tür + konu": (list(TURLER), list(KONULAR))} def ara(ziyaret, duzen): """Başlık okumak da iddia okumak da bir adımdır; bulunamayınca her şey taranır.""" soru, konu = ziyaret tur, adim = SORULAR[soru], 0 ust, alt = BOLUM[duzen] for u in ust: if u: adim += 1 if u != tur: continue for a in alt: if a: adim += 1 if a != konu: continue for i in A: if (u and i["tur"] != u) or (a and i["konu"] != a): continue adim += 1 if i["tur"] == tur and i["konu"] == konu: return adim, True return sum(BASLIK[duzen].values()) + len(A), False print(f"iddia {len(A)} | konu {len(KONULAR)} | okur ziyareti {len(ZIYARET)}") print("konu dağılımı: " + ", ".join( f"{k} {sum(i['konu'] == k for i in A)}" for k in KONULAR)) bosluk = [z for z in ZIYARET if SORULAR[z[0]] and not any( i["tur"] == SORULAR[z[0]] and i["konu"] == z[1] for i in A)] print(f"bir türe düşen ziyaret {sum(1 for s, _ in ZIYARET if SORULAR[s])} | " f"hiçbir türe düşmeyen {sum(1 for s, _ in ZIYARET if not SORULAR[s])} | " f"türü var ama karşılığı yazılmamış {len(bosluk)}") print("kapsam boşlukları:", [(SORULAR[s], k) for s, k in bosluk]) print() print(f"{'başlık düzeni':>14s} {'başlık':>7s} {'ortalama adım':>14s} {'en kötü':>8s}" f" {'bulunan':>8s} {'bulunamayan':>12s}") for duzen in BASLIK: sonuc = [ara(z, duzen) for z in ZIYARET] bulunan = [a for a, b in sonuc if b] print(f"{duzen:>14s} {sum(BASLIK[duzen].values()):7d}" f" {sum(bulunan) / len(bulunan):14.2f} {max(bulunan):8d}" f" {len(bulunan):8d} {len(sonuc) - len(bulunan):12d}") print() print("başlık iddiaları — doğru/bayat/sessiz") print(f"{'başlık düzeni':>14s}" + "".join(f" {'sürüm ' + str(s):>8s}" for s in SURUMLER)) for duzen, dagilim in BASLIK.items(): toplam, satir = sum(dagilim.values()), f"{duzen:>14s}" for s in SURUMLER: bayat = sum(n for y, n in dagilim.items() if bayat_mi(y, s)) satir += f" {f'{toplam - bayat}/{bayat}/{bayat}':>8s}" print(satir) ``` ``` iddia 56 | konu 6 | okur ziyareti 36 konu dağılımı: kurulum 13, ölçüm başlatma 8, çıktı biçimi 11, yetki 10, hata 7, ayarlar 7 bir türe düşen ziyaret 24 | hiçbir türe düşmeyen 12 | türü var ama karşılığı yazılmamış 3 kapsam boşlukları: [('öğretici', 'ölçüm başlatma'), ('nasıl yapılır', 'ayarlar'), ('referans', 'çıktı biçimi')] başlık düzeni başlık ortalama adım en kötü bulunan bulunamayan başlıksız 0 26.38 56 21 15 tür başlıklı 4 7.29 19 21 15 konu başlıklı 6 7.90 14 21 15 tür + konu 28 7.00 11 21 15 başlık iddiaları — doğru/bayat/sessiz başlık düzeni sürüm 0 sürüm 1 sürüm 2 sürüm 3 sürüm 6 sürüm 12 başlıksız 0/0/0 0/0/0 0/0/0 0/0/0 0/0/0 0/0/0 tür başlıklı 4/0/0 4/0/0 4/0/0 4/0/0 4/0/0 0/4/4 konu başlıklı 6/0/0 6/0/0 6/0/0 6/0/0 0/6/6 0/6/6 tür + konu 28/0/0 28/0/0 28/0/0 28/0/0 4/24/24 0/28/28 ``` #### Başlığın Kısalttığı İlk tablonun en büyük farkı ilk satırla ikinci satır arasındadır. Başlıksız metinde okur aradığı iddiaya ortalama **26,38** adımda ulaşıyor; en kötü durumda **56** birim, yani dokümanın tamamını okuyor. Dört başlık eklendiğinde ortalama **7,29**'a iniyor. Dört satır yazmak arama maliyetini **dörtte bire** indiriyor. İkinci fark çok daha küçüktür ve dersin asıl bulgusu odur. Altı konu başlığı **7,90** veriyor — dört tür başlığından **daha kötü**. İki ekseni iç içe koyan düzen **7,00** veriyor, yani tür başlıklı düzenden yalnız **0,29** adım daha iyi. Yirmi sekiz başlık, dört başlığın verdiğinin üstüne çeyrek adım koyuyor. Neden bu kadar az? Çünkü bir bölümün içindeki tarama zaten kısadır. Dört tür 56 iddiayı 15, 14, 12 ve 15'lik gruplara böler; ikinci bir eksen bu gruplardan birini ortalama iki üç iddiaya indirir, ama okur o gruba gelene kadar **altı alt başlık** daha okumuştur. Kazanılan tarama, ödenen başlık okumasıyla neredeyse tam olarak takas edilir. En kötü durum sütunu farklı bir şey söylüyor: **56 / 19 / 14 / 11**. Derinleşen düzen ortalamayı kıpırdatmıyor ama **en kötü durumu** düzeltiyor. Bölümlendirme derinliği ortalama okur için değil, en talihsiz okur için alınmış bir karardır. Bu satırlar ikinci bir kaldıraca da işaret ediyor. Tür başlıklı düzende başlık okuması en çok **dört** adımdır; ortalamanın geri kalanı bölüm **içindeki** taramadır. Öyleyse bir bölümün iç sırası, başlık sayısı kadar belirleyicidir. Sık sorulan iddiayı bölümün başına almak, yeni bir başlık düzeyi açmadan aynı işi görür. İki türün geleneksel olarak farklı sıralanması buradan gelir: öğretici **yapılış sırasına** göre dizilir çünkü okur adımları sırayla uygular; referans **ada göre** dizilir çünkü okur aradığı adı bilir ve sıralamayı bir dizin gibi kullanır. İki sıralama da aynı soruyu yanıtlar — okur bir sonraki birime nasıl karar verecek? #### Bulunamayan On Beş Ziyaret Otuz altı ziyaretin **15**'i dört düzenin **hiçbirinde** yanıt bulmuyor ve bu sayı düzenden düzene değişmiyor. Başlıklandırma bir metnin içinde olmayanı bulunur yapamaz. On beş başarısızlık iki ayrı kusurdan geliyor ve karıştırılmaları pahalıdır. Birincisi **12** ziyaret: "hangi sürümde değişti" ve "bu neden çalışmıyor" soruları hiçbir türe düşmez. Bu bir yazım kusuru değil, ortak tanımın ilan ettiği **taksonominin sınırıdır**; kursun sürüm notu ve sorun giderme dersleri bu iki soruyu ayrı türler olarak kurar. Bu ziyaretler için yapılacak şey başlık eklemek değil, **eksik türü yazmaktır**. İkincisi **3** ziyaret: soru bir türe düşüyor ama o türde o konuya ait tek bir iddia bile yazılmamış. Ölçüm bunları tek tek adlandırıyor — öğreticide ölçüm başlatma, nasıl yapılırda ayarlar, referansta çıktı biçimi. Bu bir **kapsam boşluğudur** ve doğrudan bir yazma listesidir. Başlık düzeni bu boşlukları görünür kılar; başlıksız metinde aynı boşluk okurun 56 birimi taradıktan sonra vardığı sessiz bir sonuçtur. Bulunamayan ziyaretin maliyeti düzen derinleştikçe artar: başlıksız metinde **56** birim, iki düzeyli düzende **84** birim taranır. Derin düzen bulunanı hızlandırırken bulunamayanı pahalılaştırır. Bir dokümanda kapsam boşluğu çoksa derinleştirme yanlış yatırımdır. #### Başlık da Bir İddiadır Alt tablo başlıkları kursun kendi eksenine sokuyor. Başlık bir cümledir ve bir yüzeye bağlanır. Tür adları **kavrama** bağlıdır: öğretici, nasıl yapılır, açıklama ve referans ürünün adlandırmasından bağımsızdır ve on ikinci sürüme kadar doğru kalır — tabloda dört başlık **4/0/0** ile ilerler ve ancak sürüm 12'de **0/4/4** olur. Konu adları **ada** bağlıdır ve ad beş sürümde bir değişir. Altı konu başlığı altıncı sürümde **0/6/6** verir. İki düzeyli düzen ikisini birden taşır: sürüm 6'da **4/24/24**, sürüm 12'de **0/28/28**. Bir ürün özelliğinin adı değiştiğinde o adı taşıyan yirmi dört alt başlık aynı anda yanlışlaşır. Üçüncü sütun bu tablonun asıl haberidir: **bayat başlıkların hepsi sessizdir.** Başlık bir çalıştırılabilir örneğe gömülemez; hiçbir sınama bir başlığın artık var olmayan bir şeyi adlandırdığını bildirmez. Doküman kurulur, sayfa açılır, başlık görünür ve yanlıştır. Karar bu iki tabloyu birlikte okuyunca çıkar. İki düzeyli düzen ortalamada **0,29** adım kazandırıyor ve karşılığında altıncı sürümde **24 sessiz bayat** başlık taşıyor. En kötü durumu 19'dan 11'e indirmesi gerçek bir kazançtır, ama bedeli bir bakım borcudur. Derinleştirmenin gerekçesi ortalama olamaz; ancak en kötü durum ya da kapsam boşluğunun görünürlüğü olabilir. #### Özet - Taranabilir metnin ölçüsü estetik değil, okurun sorusuna ulaşana kadar okuduğu **birim sayısıdır**; başlık okumak ile iddia okumak aynı birime çevrilir. - Başlıksız metin ortalama **26,38**, dört tür başlığı **7,29**, altı konu başlığı **7,90**, iki düzeyli düzen **7,00** adım ister. İlk dört başlık maliyeti dörtte bire indirir; yirmi dört alt başlık yalnız **0,29** adım ekler. - En kötü durum **56 / 19 / 14 / 11** olarak iner: derinleştirme ortalama okur için değil, **en talihsiz okur** için alınan bir karardır. - Otuz altı ziyaretin **15**'i hiçbir düzende yanıt bulmaz; **12**'si taksonominin sınırı, **3**'ü kapsam boşluğudur. Başlık düzeni boşluğu görünür kılar, kapatmaz; bulunamayan ziyaretin maliyeti derin düzende **56**'dan **84** birime çıkar. - Başlık bir iddiadır: tür adları kavrama, konu adları ada bağlıdır ve iki düzeyli düzen altıncı sürümde **24 sessiz bayat** başlık taşır — hiçbir başlık örneğe gömülemediği için başlık bayatlaması **her zaman sessizdir**. #### Sonraki Adım Buradaki bütün ölçüm tek bir sessiz varsayıma yaslanıyor: okur kendi sorusundaki sözcük ile başlıktaki sözcüğü eşleştirebiliyor. Konu başlığı "yetki" diyorsa ve okur aynı şeye "izin" diyorsa arama daha ilk adımda kırılır — okur eşleşmeyi kaçırır, yanlış bölüme girer ya da metinde iki ayrı şey olduğunu sanır. Sonraki ders bu eşleşmeyi ölçer: aynı kavramın iki adla anılması okurun bulabildiği iddia sayısını ne kadar düşürür ve bir stil rehberinin her kuralı tam olarak neyi ölçer. ### Stil Rehberi Source: https://academia.sh/tr/kurslar/teknik-yazarlik/stil-rehberi Stil rehberi bir dayatma listesi değil, her kuralın neyi ölçtüğünün yazıldığı bir belgedir; aynı kavram iki adla anıldığında okur 56 iddianın 25'ini bulabilir, 52'si belirsiz kalır ve yeniden adlandırma taramasının kaçırdığı 31 iddianın 23'ü sessizdir. Önceki dersin bütün ölçümü tek bir sessiz varsayıma yaslanıyordu: okur kendi sorusundaki sözcük ile başlıktaki sözcüğü eşleştirebiliyor. Bu varsayım her zaman tutmaz. Doküman aynı şeye iki yerde iki ad veriyorsa, okurun elindeki sözcük ikisinden yalnız birine uyar. Bu dersin sorusu ikili adlandırmanın bedelidir: **aynı kavram iki adla anıldığında okur kaç iddiaya ulaşabilir ve kaç iddia belirsiz kalır?** Yanında ikinci bir soru duruyor: stil rehberi denen belge, bu tür soruların yanıtı olmadan yazılırsa ne olur? #### Kural Değil, Ölçü Stil rehberlerinin çoğu bir yasaklar listesi biçiminde yazılır. Böyle bir liste iki nedenle işlemez. Birincisi, kuralı uygulayacak kişi kuralın neyi koruduğunu bilmediği için istisnayı tanıyamaz; kural ya körü körüne uygulanır ya da körü körüne çiğnenir. İkincisi, kural tartışılamaz: iki yazan farklı düşündüğünde ellerinde yalnız tercih vardır, ölçü yoktur. Ölçülebilir yazılmış bir madde farklıdır. Kuralın adını, **neyi ölçtüğünü**, ölçünün nasıl alındığını ve kuralın **düştüğü yeri** yazar. ```text # ornek stil rehberi maddesi , calistirilmamistir dayatma olarak yazılmış madde Kural 7: "düğüm" yerine "birim" yazmayın. ölçü olarak yazılmış madde Kural 7 — tek terim. Neyi ölçer: okurun kendi sözcüğüyle arattığında bulabildiği iddia sayısı, ve terim değiştiğinde taramanın kaçırdığı iddia sayısı. Nasıl ölçülür: bir terimin geçtiği iddialar sayılır; birincil adla yazılmış olanlar bulunan, ikinci adla yazılmış olanlar kaçan. Nerede düşer: terimin üründe gerçekten iki adı varsa. O zaman doküman ikisini de yazar, birini birincil ilan eder ve ötekini yalnız tanımın yanında anar. ``` İkinci biçim bir yasak taşımıyor; bir büyüklük taşıyor. Yazan kişi kuralı çiğnemek istediğinde neyi kaybedeceğini görüyor ve kararı gerekçesiyle verebiliyor. **Stil rehberi böyle yazıldığında bir üslup belgesi değil, bir ölçüm belgesi olur** ve dokümanın kendisi gibi denetlenebilir. #### İki Adın Ürettiği Belirsizlik Aynı kavramın iki adla anılması okurun kafasında üç ayrı okuma açar ve okur bunlardan hangisinin doğru olduğunu metinden çıkaramaz. Birinci okuma: **ikisi aynı şeydir**, yazan çeşitleme yapmıştır. İkinci okuma: **ikisi ayrı şeydir**, aralarında bilmediği bir ayrım vardır ve o ayrımı öğrenmeden ilerlememelidir. Üçüncü okuma: **biri eskidir**, ürün bir zamanlar öyle adlandırılmıştı ve doküman güncellenmemiştir. Üçü de metinden desteklenebilir; okur bir bahis oynamak zorundadır. Bu belirsizliğin bedeli yalnız yavaşlama değildir. İkinci okumayı seçen okur, olmayan bir ayrımı arayarak vakit harcar. Birinci okumayı seçen okur, iki ad gerçekten farklı şeylere karşılık geliyorsa yanlış bir işlem yapar. Ölçüm bu yüzden belirsiz iddiaları **ayrı bir sütunda** sayar: onlar yanlış değildir, karar bekletirler. #### Ses Birliği İkinci kural terimlerle değil, cümlenin kimden söz ettiğiyle ilgilidir. Bir teknik cümle ya **okura seslenir** — yapılacak bir iş bildirir — ya da **sistemi anlatır** — kendiliğinden olan bir şey bildirir. İkisi karıştığında okur her cümlede aynı kararı yeniden verir: bu bana düşen bir iş mi, yoksa olacak olan bir şey mi? **Ses birliği**, bu kararı türün düzeyine taşımaktır. Öğretici ve nasıl yapılır okura seslenir, çünkü ikisi de okurun elindeki bir işi yürütür. Açıklama ve referans sistemi anlatır, çünkü ikisi de okurdan bir eylem beklemez. Kural türe bağlandığında okur sesi cümle cümle çözmez, bölümün başında bir kez öğrenir. Bu kuralın ölçtüğü şey de bir yasak değildir: **okurun eylemin kime düştüğünü ayırt edebildiği iddia sayısıdır.** Ölçümün varsayımları: - **YD21** — 56 iddia ortak kurgudan gelir: dört tür, dört yüzey, **17** çalıştırılabilir örneğe gömülü iddia. Kâhin kurgunun kendisidir. - **YD22** — Bu dersin eklediği tek şey her iddianın andığı **terim**, kullandığı **ad** ve **sesidir**. Üçü de kurgu üreticiyle seçilir ve iddianın yüzeyine bakmaz. - **YD23** — Sekiz terim vardır ve her terimin iki adı olabilir. Bir terim birleştirilmişse bütün iddiaları birincil adı kullanır; birleştirilmemişse her iddia iki addan birini kullanır. - **YD24** — Okur **birincil adı** bilir; ikinci adla yazılmış iddiaya arama ile ulaşamaz. - **YD25** — Bir terim dokümanda **iki adıyla birden geçiyorsa** o terimin bütün iddiaları belirsiz sayılır; okur iki adın aynı şeyi mi gösterdiğini metinden çıkaramaz. - **YD26** — Üç stil rejimi denenir: **serbest** (hiçbir terim birleştirilmemiş), **kısmi** (en çok geçen dört terim birleştirilmiş), **tek terim** (sekizi de birleşik). - **YD27** — Yeniden adlandırma taraması birincil adı arar ve bulduğu her iddiayı düzeltir. İkinci adla yazılmış iddia taramanın dışında kalır ve eski adı taşımayı sürdürür; bu iddia **çalıştırılabilir örneğe gömülü değilse hiçbir ses çıkarmaz.** #### Ölçüm ```python """Stil rehberi: ayni kavramin iki adla anilmasi okurda ne uretiyor. Bolum 1 - terim dagilimi ve besinci surumde dogru/bayat/sessiz. Bolum 2 - uc stil rejimi: bulunan iddia ve belirsiz iddia. Bolum 3 - ses birligi ve yeniden adlandirma taramasinin kacirdigi. """ TOHUM = 20260816 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} TERIMLER = ("ölçüm", "düğüm", "yetki", "eşik", "günlük", "kanal", "etiket", "sağlama") # Her türün okurla kurduğu ses: iş okura mı düşer, sistem mi yapar. SES = {"öğretici": "okura", "nasıl yapılır": "okura", "açıklama": "sisteme", "referans": "sisteme"} def uretec(tohum): d = tohum % 2147483646 + 1 def r(n): nonlocal d d = (d * 48271) % 2147483647 return d % n return r 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 terim_ata(liste, tohum=TOHUM): """Bu dersin eklediği tek şey: her iddianın andığı terim, seçtiği ad ve sesi.""" r = uretec(tohum) for i in liste: i["terim"] = TERIMLER[r(len(TERIMLER))] i["ikinci_ad"] = r(2) == 0 i["ses"] = "okura" if r(2) == 0 else "sisteme" return liste def bayat_mi(i, surum): return surum // SIKLIK[i["yuzey"]] >= 1 A = terim_ata(iddialar()) sirali = sorted(TERIMLER, key=lambda t: -sum(i["terim"] == t for i in A)) REJIM = {"serbest": (), "kısmi": tuple(sirali[:4]), "tek terim": TERIMLER} def ikinci_adla(i, birlesik): """Terim birleştirilmemişse iddia iki addan birini kullanmış olabilir.""" return i["ikinci_ad"] and i["terim"] not in birlesik print(f"iddia {len(A)} | terim {len(TERIMLER)} | örneğe gömülü " f"{sum(i['gomulu'] for i in A)}") print("terim dağılımı: " + ", ".join( f"{t} {sum(i['terim'] == t for i in A)}" for t in TERIMLER)) b5 = [i for i in A if bayat_mi(i, 5)] print(f"sürüm 5 — doğru {len(A) - len(b5)} | bayat {len(b5)} | sessiz " f"{sum(not i['gomulu'] for i in b5)} (ad yüzeyi beşinci sürümde değişir)") print() print(f"{'stil rejimi':>12s} {'iki adlı terim':>15s} {'aranan adla bulunan':>20s}" f" {'belirsiz iddia':>15s}") for ad, birlesik in REJIM.items(): ikili = [t for t in TERIMLER if t not in birlesik and len({i["ikinci_ad"] for i in A if i["terim"] == t}) == 2] bulunan = sum(not ikinci_adla(i, birlesik) for i in A) belirsiz = sum(i["terim"] in ikili for i in A) print(f"{ad:>12s} {len(ikili):15d} {bulunan:20d} {belirsiz:15d}") print() print(f"{'ses rejimi':>12s} {'türünün sesiyle yazılan':>24s}" f" {'okur ile sistem karışan':>24s}") uyan = sum(i["ses"] == SES[i["tur"]] for i in A) print(f"{'karışık':>12s} {uyan:24d} {len(A) - uyan:24d}") print(f"{'ses birliği':>12s} {len(A):24d} {0:24d}") print() print(f"{'yeniden adlandırma':>18s} {'taranan':>8s} {'bulunan':>8s} {'kaçan':>7s}" f" {'kaçanın sessizi':>16s}") for ad, birlesik in REJIM.items(): kacan = [i for i in A if ikinci_adla(i, birlesik)] print(f"{ad:>18s} {len(A):8d} {len(A) - len(kacan):8d} {len(kacan):7d}" f" {sum(not i['gomulu'] for i in kacan):16d}") ``` ``` iddia 56 | terim 8 | örneğe gömülü 17 terim dağılımı: ölçüm 7, düğüm 10, yetki 4, eşik 8, günlük 8, kanal 6, etiket 7, sağlama 6 sürüm 5 — doğru 11 | bayat 45 | sessiz 28 (ad yüzeyi beşinci sürümde değişir) stil rejimi iki adlı terim aranan adla bulunan belirsiz iddia serbest 7 25 52 kısmi 3 42 19 tek terim 0 56 0 ses rejimi türünün sesiyle yazılan okur ile sistem karışan karışık 28 28 ses birliği 56 0 yeniden adlandırma taranan bulunan kaçan kaçanın sessizi serbest 56 25 31 23 kısmi 56 42 14 8 tek terim 56 56 0 0 ``` #### Yarısını Bulamayan Okur İlk tablonun orta sütunu dersin ana sayısıdır. Serbest rejimde okur kendi bildiği adla arattığında 56 iddianın **25**'ini buluyor. Kalan **31** iddia dokümanda duruyor, doğru duruyor, ama okurun sözcüğüyle bulunmuyor. Bu bir yazım kusuru değil, bir **erişim** kusurudur ve önceki dersin ölçtüğü mesafeye eklenir: okur bölümü doğru bulsa bile cümleyi tanımaz. Sağdaki sütun daha ağırdır. Serbest rejimde **52** iddia belirsizdir; yani 56 iddianın neredeyse tamamı, okura "bu iki ad aynı şey mi" sorusunu bir kez daha sordurur. Belirsizlik tek tek iddialara değil, **terime** yayılır: bir terim iki adla anıldığı anda o terimin bütün iddiaları belirsizleşir, ikinci adla yazılmamış olanlar da dahil. Sol sütun bir ayrıntıyı açığa vuruyor: serbest rejimde sekiz terimin **7**'si iki adla geçiyor, sekizincisi değil. O terimin dört iddiasının hepsi kurguda aynı adı seçmiş. Kural yokken tekliğe rastlantıyla da varılabilir; ama bu bir düzen değildir ve bir sonraki yazılan cümlede bozulur. **Kuralın işlevi tekliği üretmek değil, tekliği garanti etmektir.** Orta satır kuralın nasıl sıralanacağını söylüyor. En çok geçen **dört** terimi birleştirmek bulunanı 25'ten **42**'ye çıkarıyor, belirsizi 52'den **19**'a indiriyor. Sekiz terimin yarısı, belirsizliğin üçte ikisini kapatıyor. Bir stil rehberi baştan sona uygulanamıyorsa, **terimleri geçiş sıklığına göre sıraya koymak** kuralın büyük bölümünü ilk hamlede ödetir. #### Ses Karıştığında İkinci tablo daha kaba bir sonuç veriyor: karışık rejimde 56 iddianın **28**'i türünün sesiyle yazılmış, **28**'i değil. Yani okur her iki cümleden birinde eylemin kime düştüğüne kendisi karar veriyor. Bir öğreticide sistemin sesiyle yazılmış cümle okura yapılacak işi gizler; bir referansta okurun sesiyle yazılmış cümle olmayan bir görev icat eder. Bu sayının 28 çıkması kurgudan gelir ve önemli olan büyüklüğü değil, **karar sayısının iddia sayısıyla orantılı** olmasıdır. Ses birliği kuralı bu kararı 56 defadan bire indirir: tür seçildiğinde ses de seçilmiş olur. Kuralın ölçtüğü şey budur ve bir üslup tercihi olarak yazılmasının hiçbir gerekçesi yoktur. #### Birincil Adı Kim Belirler Ölçüm bir şeyi söylemiyor: birincil adın **hangi ad** olacağını. Bu boşluk kuralın en kritik yerindedir, çünkü yanlış doldurulursa tek terim kuralı sayıyı 56'ya çıkarır ve okura hiçbir şey kazandırmaz. Okurun elindeki sözcük dokümandan gelmez; **ürünün yüzeyinden** gelir. Okur yazdığı seçeneği, gördüğü alanı ve aldığı iletiyi okumuştur. Doküman kendi içinde tutarlı ama üründe görünmeyen bir ad seçerse, okurun getirdiği sözcük hiçbir iddiaya değmez. Kuralın doğru biçimi bu yüzden "tek ad kullan" değil, **"birincil ad ürünün yüzeyinde görünen addır"** biçimidir. Terimin üründe gerçekten iki adı olduğu durum kuralın düştüğü yerdir ve gerçekten olur: aynı ayarın bir komut seçeneği adı, bir de yapılandırma anahtarı adı vardır. Böyle bir terimde doküman ikisini de **bir kez** yazar, hangisinin birincil olduğunu ilan eder ve sonraki bütün iddialarda yalnız birincil adı kullanır. İkinci ad tanımın yanında bir kez geçtiği için okur eşleştirmeyi yapabilir; iddialara yayılmadığı için de tarama onu kaçırmaz. Belirsizlik böylece 56 iddiadan tek bir satıra indirilmiş olur. Bu bağ terim işini doğrudan **ad yüzeyine** bağlar. Ürünün adı değiştiğinde dokümanın adı da değişmek zorundadır ve bu bir üslup bakımı değil, bayatlama bakımıdır. #### Yeniden Adlandırma Taraması Son tablo dersi kursun eksenine bağlıyor. Ürünün bir terimi yeniden adlandırıldığında bakım yapan kişi metni tarar ve bulduğunu düzeltir. Serbest rejimde tarama **25** iddiayı buluyor, **31**'ini kaçırıyor — çünkü tarama birincil adı arıyor, kaçanlar ikinci adla yazılmış. Kaçanların **23**'ü **sessizdir**. Bu iddialar çalıştırılabilir örneğe gömülü olmadığı için eski adı taşımaya devam eder ve hiçbir sınama, hiçbir kurma adımı, hiçbir okur bunu bildirmez. Ses çıkaran **8** iddia örneğe gömülü olanlardır; örnek artık tanınmayan bir adı kullandığı için çalışmaz. **Tek terim kuralının kurtardığı asıl şey okurun araması değil, bakımın taramasıdır.** Üst satırdaki sürüm 5 ölçümü bunun neden acil olduğunu söylüyor. Ad yüzeyi beşinci sürümde değişir; o sürümde dokümanın **45** iddiası bayat, **28**'i sessiz bayat ve doğru kalan yalnız **11** iddia vardır. Yeniden adlandırma, bayatlamanın en sık gelen biçimidir ve tek terim kuralı onu tek tarama ile kapatılabilir bir işe indirir. İkili adlandırma ise aynı işi **iki kat yüzeye** yayar ve yarısını görünmez kılar. #### Özet - Stil rehberi bir yasaklar listesi olarak yazıldığında istisna tanınamaz ve kural tartışılamaz. Ölçülebilir madde kuralın adını, **neyi ölçtüğünü**, nasıl ölçüldüğünü ve **nerede düştüğünü** yazar. - İkili adlandırma okurun kafasında üç okuma açar — aynı şey, ayrı şeyler, biri eski — ve metin bunlardan hangisinin doğru olduğunu söylemez. Belirsizlik terime yayılır: serbest rejimde **52** iddia belirsizdir. - Okur kendi adıyla arattığında serbest rejimde 56 iddianın **25**'ini bulur. En çok geçen dört terimi birleştirmek bulunanı **42**'ye çıkarır, belirsizi **19**'a indirir. - Ses birliği, eylemin kime düştüğü kararını 56 cümleden bir tür seçimine indirir; karışık rejimde iddiaların **28**'i türünün sesiyle yazılmamıştır. - Terim yeniden adlandırıldığında serbest rejimde tarama **31** iddiayı kaçırır ve kaçanların **23**'ü sessizdir; ses çıkaran **8**'i yalnız çalıştırılabilir örneğe gömülü olanlardır. #### Sonraki Adım Son tablo bir ayrımı ortaya çıkardı ve o ayrım kursun merkezindedir: kaçan 31 iddianın 8'i ses çıkardı, 23'ü çıkarmadı. Ses çıkaranların tek ortak özelliği **çalıştırılabilir bir örneğe gömülü** olmalarıydı. Öyleyse doğal soru şudur: bir dokümanın kaç iddiası gerçekten gömülüdür ve gömülülük oranı yükseltilirse sessiz bayatlama ne kadar geriler? Sonraki ders bu oranı ölçer, örneğin çalışır ve eksiksiz olmasının ne demek olduğunu tanımlar ve kendi örneğini de aynı ölçüte tabi tutar. ### Örnek ve Kod Parçacıkları Source: https://academia.sh/tr/kurslar/teknik-yazarlik/ornek-ve-kod-parcaciklari Çalıştırılabilir örneğe gömülü iddia bayatlayınca ses çıkarır, gömülü olmayan çıkarmaz; 56 iddianın 17'si gömülüdür ve on ikinci sürümde bayatlayan 56 iddianın 39'u sessizdir — 0,6964. Önceki ders bir ayrımı ortaya çıkardı. Terim yeniden adlandırıldığında tarama **31** iddiayı kaçırdı; bunların **8**'i ses çıkardı, **23**'ü çıkarmadı. Ses çıkaranların tek ortak özelliği vardı: çalıştırılabilir bir örneğin **içinde** duruyorlardı. Bu dersin sorusu o özelliğin adını koymak ve bedelini ölçmektir: **bir dokümanın kaç iddiası gerçekten gömülüdür, gömülülük oranı değiştirilirse sessiz bayatlama ne kadar geriler ve nerede geri çekilmeyi bırakır?** #### Gömülü İddia ile Yanındaki Cümle Bir örneğin çevresinde iki ayrı cümle türü bulunur ve ikisi bayatlama karşısında bambaşka davranır. Birincisi **örneğin kendisidir**. Örnek bir çağrının biçimini, bir alanın adını, bir adımın sırasını iddia eder; bu iddialar cümle olarak yazılmamıştır, **kod olarak** yazılmıştır. Ürün değiştiğinde örnek çalışmaz ve bu bir olaydır: sınama düşer, kurma adımı kırılır, okur bir hata iletisi alır. **Gömülü iddia**, doğruluğu çalıştırılarak sınanabilen iddiadır. İkincisi **örneğin yanına yazılmış cümledir**: "bu çağrı eşik alanını yüzde olarak alır". Aynı bilgiyi taşır, aynı şeye bağlıdır, ama hiçbir yerde sınanmaz. Ürün eşik alanını saniyeye çevirdiğinde örnek yine çalışır — sayı geçerlidir, yalnız anlamı değişmiştir — ve cümle sessizce yanlışlaşır. Ayrım bu yüzden "örnek var mı" sorusuyla ölçülmez. **Aynı iddianın örneğin içinde mi yoksa yanında mı durduğuyla ölçülür.** Yanındaki cümlelerin çoğu, örneğin içine taşınabilir: alanın birimi bir doğrulama satırıyla, dönen alanın varlığı bir yazdırmayla, sıranın önemi adımların gerçekten sırayla çalışmasıyla iddia edilebilir. #### Çalışır, Eksiksiz, Doğrulanabilir Gömülülük bir niyet değil, bir özelliktir ve üç koşulu birden ister. Üçü ayrı ayrı tanımlanır çünkü ayrı ayrı düşerler. **Çalışır:** örnek kopyalanıp çalıştırıldığında yürür. Eksik bir alma satırı, tanımsız bir değişken ya da yorum içinde bırakılmış bir seçenek örneği çalışmaz yapar. **Eksiksiz:** örnek dışarıdan hiçbir tanım beklemez. Bir önceki örnekte kurulmuş bir değişkeni kullanan parçacık, tek başına kopyalandığında düşer; okur çoğunlukla tek başına kopyalar. **Doğrulanabilir:** örneğin beklenen çıktısı yanında yazılıdır ve karşılaştırılabilir. Çıktısı yazılmamış bir örnek çalışır ama **yanlış çalıştığı fark edilmez**; ses çıkarması için düşmesi gerekir, oysa çoğu bayatlama düşmeden, yalnız farklı bir sonuç vererek gelir. ```text # ornek dokuman parcasi , calistirilmamistir parçacık olarak yazılmış örnek sonuc = olcum.baslat(esik = 5) print(sonuc.ozet) Metindeki cümle: "baslat çağrısı esik alanını yüzde olarak alır." eksiksiz örneğe dönüşmesi için gereken satırlar - olcum'un nereden geldiği - baslat çağrılabilsin diye kurulması gereken bağlam - ozet alanının gerçekten döndüğünün yazdırılması - beklenen çıktının örneğin yanında durması ``` Üstteki parçacık üç koşulun üçünü de karşılamaz. Çalışmaz, çünkü ilk ad tanımsızdır. Eksiksiz değildir, çünkü bağlamı başka bir yerdedir. Doğrulanabilir değildir, çünkü ne yazdıracağı yazılı değildir. **Böyle bir parçacık gömülü görünür ama gömülü değildir:** bayatladığında ses çıkarmaz, çünkü zaten çalışmıyordur. #### Bu Dersin Kendi Örneği Bu ders "çalışır, eksiksiz ve doğrulanabilir örnek" diyorsa kendi örneği de öyle olmak zorundadır; yoksa dersin kendisi yukarıdaki parçacığın durumuna düşer. Aşağıdaki ölçüm bloğu bu üç koşulu karşılar. Dışarıdan hiçbir tanım beklemez: türler, yüzeyler, sıklıklar ve gömülülük oranları bloğun içindedir. Kopyalanıp çalıştırıldığında yürür. Ardından gelen etiketsiz blok, bu bloğun **gerçekten alınmış çıktısıdır**; elle yazılmamıştır ve karşılaştırılabilir. Dersin bütün sayı iddiaları o çıktıdan gelir; hiçbiri metinden gelmez. Ölçümün varsayımları: - **YD31** — 56 iddia ortak kurgudan gelir: dört tür, dört yüzey. 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. - **YD32** — Bir iddia, bağlandığı yüzey o sürüme kadar en az bir kez değiştiyse bayattır. Yüzey sıklıkları değişmez: imza **2**, akış **3**, ad **5**, kavram **12** sürümde bir. - **YD33** — Gömülü bir iddia bayatlayınca **ses çıkarır**; gömülü olmayan bayatlayınca hiçbir şey olmaz ve **sessiz** sayılır. - **YD34** — **Kavram yüzeyine bağlı iddia hiçbir örneğe gömülemez.** Bir örnek bir şeyin neden öyle olduğunu çalıştırarak iddia edemez; yalnız nasıl davrandığını iddia edebilir. - **YD35** — Bu dersin değiştirdiği tek şey **gömülülük oranıdır**. Türlerin yüzey dağılımı ve yüzeylerin sıklığı ortak tanımdaki gibidir. - **YD36** — Üç gömülülük rejimi denenir: **parçacık** (oranlar yarıya iner; eksik yazılmış örnek gömülü sayılmaz), **ortak tanım** (kurgunun kendi oranları), **tam örnek** (her tür örneklerini eksiksiz yazar, referans da örnek taşır). - **YD37** — Sessizlik oranı bayatlayanlar üzerinden hesaplanır; hiçbir iddianın bayat olmadığı sürümlerde oran tanımsızdır. #### Ölçüm ```python """Ornek ve kod parcaciklari: gomulu iddia ses cikarir, gomulu olmayan cikarmaz. Bolum 1 - gomulu iddialarin turlere dagilimi. Bolum 2 - surum surum dogru/bayat/sessiz ve sessizin bayata orani. Bolum 3 - bu dersin degistirdigi tek sey: gomululuk orani. """ TOHUM = 20260816 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} SURUMLER = (0, 1, 2, 3, 6, 12) # Bu dersin değiştirdiği tek şey: gömülülük oranı. Yüzeyler ve türler sabit. REJIM = { "parçacık": {t: o / 2 for t, o in ORNEKLI.items()}, "ortak tanım": ORNEKLI, "tam örnek": {"öğretici": 0.80, "nasıl yapılır": 0.85, "açıklama": 0.40, "referans": 0.60}, } def iddialar(oranlar=ORNEKLI): """Her iddia: türü, bağlandığı yüzey, çalıştırılabilir örneğe gömülü mü.""" liste, no = [], 0 for tur, dagilim in TURLER.items(): hedef = 0 for yuzey, adet in dagilim.items(): for _ in range(adet): no += 1 hedef += oranlar[tur] gomulu = hedef >= 1 and yuzey != "kavram" if gomulu: hedef -= 1 liste.append({"no": no, "tur": tur, "yuzey": yuzey, "gomulu": gomulu}) return liste def bayat_mi(i, surum): return surum // SIKLIK[i["yuzey"]] >= 1 def olc(liste, surum): """Doğru kalan, bayatlayan ve bayatlayanın sessiz olanı.""" bayat = [i for i in liste if bayat_mi(i, surum)] sessiz = [i for i in bayat if not i["gomulu"]] return len(liste) - len(bayat), len(bayat), len(sessiz) A = iddialar() print(f"iddia {len(A)}, tür {len(TURLER)}, " f"örneğe gömülü {sum(1 for i in A if i['gomulu'])}") print("gömülü dağılımı: " + ", ".join( f"{t} {sum(i['gomulu'] for i in A if i['tur'] == t)}" for t in TURLER)) print() print(f"{'sürüm':>6s} {'doğru':>6s} {'bayat':>6s} {'sessiz':>7s} {'sessiz/bayat':>13s}") for s in SURUMLER: dogru, bayat, sessiz = olc(A, s) oran = f"{sessiz / bayat:.4f}" if bayat else "-" print(f"{s:6d} {dogru:6d} {bayat:6d} {sessiz:7d} {oran:>13s}") print() print(f"{'gömülülük rejimi':>17s} {'gömülü':>7s} {'sürüm 12 bayat':>15s}" f" {'sessiz':>7s} {'sessiz/bayat':>13s}") for ad, oranlar in REJIM.items(): liste = iddialar(oranlar) dogru, bayat, sessiz = olc(liste, 12) print(f"{ad:>17s} {sum(1 for i in liste if i['gomulu']):7d} {bayat:15d}" f" {sessiz:7d} {sessiz / bayat:13.4f}") print() print(f"{'tür':>15s} {'gömülü':>7s} {'sürüm 3 sessiz':>15s} {'sürüm 12 sessiz':>16s}") for t in TURLER: grup = [i for i in A if i["tur"] == t] print(f"{t:>15s} {sum(i['gomulu'] for i in grup):7d}" f" {olc(grup, 3)[2]:15d} {olc(grup, 12)[2]:16d}") ``` ``` iddia 56, tür 4, örneğe gömülü 17 gömülü dağılımı: öğretici 8, nasıl yapılır 9, açıklama 0, referans 0 sürüm doğru bayat sessiz sessiz/bayat 0 56 0 0 - 1 56 0 0 - 2 34 22 17 0.7727 3 18 38 24 0.6316 6 11 45 28 0.6222 12 0 56 39 0.6964 gömülülük rejimi gömülü sürüm 12 bayat sessiz sessiz/bayat parçacık 8 56 48 0.8571 ortak tanım 17 56 39 0.6964 tam örnek 31 56 25 0.4464 tür gömülü sürüm 3 sessiz sürüm 12 sessiz öğretici 8 5 7 nasıl yapılır 9 4 5 açıklama 0 2 12 referans 0 13 15 ``` #### Bayatlamanın Çoğu Sessizdir İlk tablo kursun üçüncü iddiasını ödüyor. On ikinci sürümde 56 iddianın **56**'sı bayattır ve bunun **39**'u sessizdir: **0,6964**. Dokümanın üçte ikisi yanlıştır ve yanlış olduğunu kimseye söylememektedir. Sayı yalnız son satırda büyük değil. İkinci sürümde bayatlayan 22 iddianın **17**'si sessizdir — oran **0,7727** ile en yüksek noktasındadır. Bunun nedeni ilk bayatlayan yüzeyin **imza** olması ve imza iddialarının büyük bölümünün referansta durmasıdır; referansın gömülü iddiası yoktur. **Dokümanın en erken bayatlayan bölümü, aynı zamanda en sessiz bölümüdür.** Oran üçüncü ve altıncı sürümde **0,6316** ve **0,6222**'ye iner. Bu düşüş bir iyileşme değil: akış yüzeyi devreye girer, akış iddialarının çoğu öğretici ile nasıl yapılırdadır ve o iki tür gömülü örnek taşır. Yani ses çıkaran iddialar bu aralıkta bayatlar. On ikinci sürümde kavram yüzeyi de düşünce oran yeniden yükselir, çünkü kavram iddiaları hiçbir zaman gömülü olamaz. Bu oranın pratik anlamı bir yanılsamadır. Bir ekip dokümanının sağlığını "ne kırıldı" sorusuyla izliyorsa, on ikinci sürümde eline **17** bildirim geçer ve bunların hepsini düzeltir. Düzeltme bittiğinde dokümanın hatasız olduğuna inanır. Gerçek sayı ise **56** bayat iddiadır; görülmeyen **39**'u yerinde durmaktadır. **Ses çıkaran bayatlamayı düzeltmek, sessiz bayatlamayı görünmez olmaktan çıkarmaz; tersine, dokümanı sağlıklı gösteren bir kanıt üretir.** Bu kümede ölçülebilen en küçük fark **1/56 = 0,0179**'dur. Rejimler arasındaki farklar bunun kat kat üstündedir ve karşılaştırılabilir; 0,6316 ile 0,6222 arasındaki fark ise tek bir iddiadan küçüktür ve bir eğilim olarak okunmamalıdır. #### Gömülülüğü Yükseltmek İkinci tablo dersin değiştirdiği tek şeyi gösteriyor. Aynı 56 iddia, aynı yüzeyler, aynı sıklıklar; değişen yalnız kaç iddianın çalıştırılabilir örneğe gömüldüğü. **Parçacık** rejiminde gömülü iddia **8**'e düşüyor ve sessizlik **0,8571**'e çıkıyor. Bu rejim örneği olmayan bir dokümanı anlatmıyor; **örneği olan ama eksiksiz olmayan** bir dokümanı anlatıyor. Yarım yazılmış örnek sayfada durur, okura bir şey gösterir ve bayatladığında hiçbir şey söylemez. **Tam örnek** rejiminde gömülü iddia **31**'e çıkıyor, sessizlik **0,4464**'e iniyor. Sessiz iddia sayısı 39'dan **25**'e düşüyor: on dört iddia sessiz olmaktan çıkıp ses çıkaran sınıfa geçiyor. Referansın da çalıştırılabilir örnek taşıması bu farkın büyük bölümünü üretiyor. Tablo aynı zamanda bir tabanı gösteriyor: sessizlik **sıfırlanmıyor**. En yüksek oranlarda bile 25 iddia sessiz kalıyor, çünkü **kavram yüzeyine bağlı iddialar hiçbir örneğe gömülemez**. Bir örnek bir şeyin nasıl davrandığını çalıştırarak iddia edebilir; **neden öyle olduğunu** iddia edemez. Gömülülük bir bakım aracıdır ve erişemediği bir bölge vardır; o bölge için doküman denetiminden başka yol yoktur. #### Kopya Gömülü Değildir Tablo bir şeyi sormuyor: bir iddiayı gömülü yapan tam olarak nedir? Sayfadaki kod bloğu kendi başına metindir; hiçbir metin bayatladığını kendi kendine bildirmez. Ses çıkaran şey **aynı metnin bir yerde gerçekten çalıştırılmasıdır**. Bunun iki yolu vardır. Birincisi dokümandaki örneğin **kendisinin** çalıştırılmasıdır — bu dersteki ölçüm bloğu gibi. İkincisi örneğin, çalıştırılan bir kaynaktan **alınmasıdır**; doküman kodu barındırmaz, gösterir. Üçüncü bir durum vardır ve en aldatıcı olan odur: **kopya**. Ekip örnekleri sınanan bir yerde tutar, dokümana da onların bir kopyasını yapıştırır. Kaynak sınanır, doğru kalır ve herkes örneklerin sınandığını sanır. Oysa sınanan kopya değildir; ürün değiştiğinde kaynak düzeltilir, doküman düzeltilmez ve iki metin sessizce ayrışır. Kopyalanmış örnek ölçümde **gömülü sayılmaz**; dokümanı doğrudan üstteki **parçacık** sütununa taşır ve sessizliği **0,8571**'e çıkarır. Kopyanın maliyeti, örneksizliğin maliyetinden büyüktür: örneği olmayan doküman kimseyi yanıltmaz, kopyalı doküman hem okuru hem yazanı yanıltır. Bu ölçütün ikinci sonucu örneğin **boyutudur**. Eksiksizlik koşulu örneği uzatır; önceki dersin ölçtüğü taranabilirlik ise uzunluğu cezalandırır — okur her satırı bir adım olarak öder. İki koşul gerçekten çekişir ve çözüm ortada bir yerde değildir. Doğru ayar **en küçük eksiksiz örnektir**: gerçek kullanımın tamamını değil, iddiayı taşıyan en kısa çalışır bütünü yazmak. Örnekten çıkarılan her satır bir iddiayı gömülü olmaktan çıkarır; bu yüzden çıkarma kararı estetik değil, ölçülebilir bir karardır — hangi iddiadan ses almaktan vazgeçiliyor? Örneğin kaynakla birlikte sürümlenmesi ve inceleme sürecine girmesi bu konunun işi değildir; kursun son konusu doküman işletimini ayrıca kurar. Burada ölçülen yalnız şudur: bir iddia, ancak onu taşıyan metin gerçekten çalıştırılıyorsa ses çıkarır. #### Sessizliğin Tür Dağılımı Son tablo dört türü sessizlik açısından karşılaştırıyor ve bir tersliği açığa vuruyor. **Açıklama** en uzun yaşayan türdür — üçüncü sürümde yalnız **2** sessiz iddiası vardır. On ikinci sürümde ise **12** iddiasının **12**'si sessiz bayattır: tür bütünüyle, tek bir uyarı üretmeden yanlışlaşır. **Referans** tersini yapar: üçüncü sürümde zaten **13** sessiz iddia taşır ve on ikinci sürümde **15**'e çıkar. Hızlı bayatlar ve baştan sona sessizdir. Öğretici ile nasıl yapılır ise sırasıyla **7** ve **5** sessiz iddiayla en iyi durumdadır; ikisi birlikte 17 gömülü iddianın tamamını taşır. Sonuç yazma önceliğini belirler. En çok örnek taşıyan iki tür zaten en çok ses çıkaran türlerdir; oraya bir örnek daha eklemenin kazancı sınırlıdır. Kazanç, **hiç örneği olmayan türlerdedir**: referansın 15 iddiası ile açıklamanın 12 iddiası, ürünün geri kalanının tümünden daha sessizdir. #### Özet - Gömülü iddia örneğin **içinde** durur ve çalıştırılarak sınanır; örneğin **yanına** yazılmış cümle aynı bilgiyi taşır ama sınanmaz ve sessizce yanlışlaşır. - Örnek üç koşulu birden ister: **çalışır**, **eksiksiz**, **doğrulanabilir**. Üçünden biri düşerse örnek gömülü görünür ama gömülü değildir. Bu dersin kendi ölçüm bloğu üç koşulu da karşılar ve çıktısı gerçekten alınmıştır. - On ikinci sürümde 56 iddianın **56**'sı bayat, **39**'u sessizdir: **0,6964**. En yüksek sessizlik ikinci sürümdedir (**0,7727**), çünkü ilk bayatlayan yüzey imzadır ve imza iddialarının çoğu örneksiz referanstadır. - Gömülülük oranı değiştiğinde sessizlik **0,8571** ile **0,4464** arasında hareket eder; yarım yazılmış örnek gömülülüğü 17'den **8**'e düşürür, eksiksiz örnek **31**'e çıkarır. - Sessizlik sıfırlanamaz: kavram yüzeyine bağlı iddialar hiçbir örneğe gömülemez. En sessiz iki tür açıklama (**12/12**) ve referanstır (**15**); örnek eklemenin kazancı oradadır. #### Sonraki Adım Örnek, dokümanda kendi kendini sınayabilen tek öğedir. Metnin yanında duran ikinci bir öğe daha vardır ve o hiçbir koşulda çalıştırılamaz: **diyagram**. Diyagram da iddia taşır — bir bileşenin adını, bir akışın sırasını, bir kavramın yapısını — ve taşıdığı iddialar tıpkı cümleler gibi bir yüzeye bağlanır. Sonraki ders diyagramın hangi yüzeye bağlandığını, bu seçimin bayatlama hızını nasıl belirlediğini ve görsel bayatlamasının neden istisnasız sessiz olduğunu ölçer. ### Görsel Kullanımı Source: https://academia.sh/tr/kurslar/teknik-yazarlik/gorsel-kullanimi Diyagramın bayatlama hızını çizim biçimi değil bağlandığı yüzey belirler: arayüz şeması ikinci sürümde yanlışlaşır, kavram şeması on ikincide; diyagram çalıştırılamadığı için taşıdığı her bayat iddia sessizdir ve karma şema on ikinci sürümde 56 iddianın 56'sını sessizleştirir. Önceki ders örneği dokümanın kendi kendini sınayabilen tek öğesi olarak kurdu: gömülü iddia bayatlayınca ses çıkarır. Metnin yanında duran ikinci bir öğe daha vardır ve o hiçbir koşulda çalıştırılamaz. **Diyagram** da iddia taşır. Bir bileşenin adını, bir akışın sırasını, bir alanın biçimini, bir kavramın yapısını iddia eder ve bu iddialar tıpkı cümleler gibi bir yüzeye bağlanır. Bu dersin sorusu şudur: **diyagram hangi yüzeye bağlanır, bu seçim bayatlama hızını nasıl belirler ve görsel bayatlaması neden istisnasız sessizdir?** Gösterimin kendisi — neyin gösterilebileceği, bir gösterimin neyi soyutladığı, aynı şeyin farklı gösterimlerinin neyi ayırt ettiği — **Modelleme ve Gösterim** kursunda kuruldu ve burada tekrarlanmaz. Burada ölçülen tek şey diyagramın **metne hizmet edip etmediğidir**: taşıdığı iddialar ne kadar yaşar ve yanlışlaştıklarında bunu kim duyar. #### Diyagram Bir İddia Kümesidir Bir diyagram süs değildir; bir dizi cümlenin resim biçiminde yazılmış hâlidir. Üç kutu ve aralarındaki iki ok, en az beş iddia taşır: üç şeyin var olduğu, ikisinin belirli bir yönde bağlandığı ve bağlantının sırası. Bu iddiaların hepsi doğru ya da yanlış olabilir; ürün değiştiğinde bir bölümü yanlışlaşır. Diyagramı metinden ayıran şey iddia taşıması değil, **taşıdığı iddiaların hiçbirinin çalıştırılamaması**dır. Bir örnek düşerse haber verir; bir resim hiçbir zaman düşmez. Sayfa kurulur, resim yerinde durur, çizgiler eskisi gibi görünür ve okur onlara güvenir. Önceki dersin diliyle: **diyagrama taşınan her iddia, gömülülük ihtimalini yitirir.** İkinci fark aramadır. Bir terim yeniden adlandırıldığında metin taraması diyagramın içine giremez; resmin içindeki eski ad taramanın dışında kalır. Üçüncü dersin ölçtüğü kaçan iddia sorunu, diyagramda **kaçınılmaz** hâle gelir. Bu iki fark, bir resmin ne zaman çizilmeye değdiğinin ölçütünü de verir. Metin doğrusaldır: cümleler bir sırayla okunur ve bu sıra bir iddiadır. Bir dizi adımı anlatmak metnin doğal işidir, çünkü sıranın kendisi zaten metnin biçimidir. Buna karşılık **aynı anda duran ilişkiler** metinde kötü sıralanır; üç şeyin birbirine hangi yönde bağlandığını okumak, üç cümleyi okuyup zihinde birleştirmeyi gerektirir. Diyagramın kazandırdığı şey budur ve tek budur. Bir resim, yanındaki paragrafın **sırasını** tekrarlıyorsa hiçbir şey kazandırmamış, yalnız bir bakım borcu eklemiştir. #### Diyagramın Bağlandığı Yüzey Diyagramlar çizim tekniğine göre değil, **neyi gösterdiklerine** göre ayrılır ve bu ayrım doğrudan yüzey ayrımıdır. **Arayüz şeması** alanları, tipleri ve çağrı biçimlerini gösterir: **imza** yüzeyi. **Akış şeması** adımların sırasını gösterir: **akış** yüzeyi. **Bileşen şeması** parçaların adlarını ve aralarındaki bağı gösterir: **ad** yüzeyi. **Kavram şeması** bir şeyin neden öyle kurulduğunu gösterir — hangi kısıt hangi kararı doğurdu: **kavram** yüzeyi. Bir diyagram birden çok yüzeyi birden gösterebilir ve gerçekte çoğu öyledir. Böyle bir resmin ömrü, taşıdığı **en hızlı yüzeyin** ömrüdür: içindeki tek bir alan adı değiştiğinde resmin tamamı artık güvenilmezdir, çünkü okur resmin hangi bölümünün eskidiğini ayırt edemez. Ölçümün varsayımları: - **YD41** — 56 iddia ortak kurgudan gelir: dört tür, dört yüzey, **17** çalıştırılabilir örneğe gömülü iddia. Kâhin kurgunun kendisidir. - **YD42** — Bu dersin eklediği tek şey iddianın **nerede taşındığıdır**: metinde mi, diyagramda mı. Türlerin yüzey dağılımı ve yüzey sıklıkları değişmez. - **YD43** — **Diyagrama taşınan hiçbir iddia örneğe gömülü olamaz.** Diyagram çalıştırılamaz; bayatladığında hiçbir sınama düşmez. - **YD44** — Bir diyagram bağlandığı yüzeyin iddialarının **tamamını** devralır. Bu bir üst sınırdır ve beş diyagram seçimini birbiriyle karşılaştırılabilir kılar. - **YD45** — Birden çok yüzey gösteren diyagram, **en hızlı yüzeyinin** sürümünde bütün olarak yanlışlaşır. - **YD46** — İki kip ölçülür: **değiştiren** diyagram iddiaları metinden alır, **tekrarlayan** diyagram aynı iddiaları metinde bırakıp bir kopyasını daha üretir. - **YD47** — Bir iddianın bayat olup olmadığı yalnız bağlandığı yüzeye ve sürüme bakar; nerede taşındığı bunu değiştirmez, yalnız **duyulup duyulmadığını** değiştirir. #### Ölçüm ```python """Gorsel kullanimi: diyagram hangi yuzeye baglaniyor ve ne hizla bayatliyor. Bolum 1 - bes diyagram secimi: tasidigi iddia, metinde gomulu olan, ilk yanlis surum. Bolum 2 - diyagram metni degistirdiginde dogru/bayat/sessiz. Bolum 3 - diyagram metni tekrarladiginda eklenen sessiz iddia. """ 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} # Her diyagram bir ya da birden çok yüzeye bağlanır. Diyagram çalıştırılamaz: # taşıdığı hiçbir iddia örneğe gömülü olamaz. DIYAGRAM = {"kavram şeması": ("kavram",), "bileşen şeması": ("ad",), "akış şeması": ("akis",), "arayüz şeması": ("imza",), "karma şema": ("imza", "akis", "ad")} 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 bayat_mi(i, surum): return surum // SIKLIK[i["yuzey"]] >= 1 def olc(liste, surum): bayat = [i for i in liste if bayat_mi(i, surum)] sessiz = [i for i in bayat if not i["gomulu"]] return len(liste) - len(bayat), len(bayat), len(sessiz) def gorselle(liste, yuzeyler, kip): """Diyagram metni değiştirebilir ya da tekrarlayabilir; ikisinde de sessizleşir.""" if kip == "değiştiren": return [dict(i, gomulu=i["gomulu"] and i["yuzey"] not in yuzeyler) for i in liste] kopya = [dict(i, gomulu=False) for i in liste if i["yuzey"] in yuzeyler] return liste + kopya A = iddialar() tumu = gorselle(A, tuple(SIKLIK), "değiştiren") print(f"iddia {len(A)} | metinde örneğe gömülü {sum(i['gomulu'] for i in A)} | " f"tümü diyagrama taşınsa gömülü {sum(i['gomulu'] for i in tumu)}") print() print(f"{'diyagram':>15s} {'yüzey':>14s} {'iddia':>6s} {'metinde gömülü':>15s}" f" {'ilk yanlış sürüm':>17s}") for ad, yuzeyler in DIYAGRAM.items(): grup = [i for i in A if i["yuzey"] in yuzeyler] print(f"{ad:>15s} {'+'.join(yuzeyler):>14s} {len(grup):6d}" f" {sum(i['gomulu'] for i in grup):15d}" f" {min(SIKLIK[y] for y in yuzeyler):17d}") print() print("diyagram metni değiştirdiğinde — doğru/bayat/sessiz") print(f"{'diyagram':>15s} {'sürüm 3':>12s} {'sürüm 6':>12s} {'sürüm 12':>12s}") for ad in ["diyagramsız"] + list(DIYAGRAM): liste = A if ad == "diyagramsız" else gorselle(A, DIYAGRAM[ad], "değiştiren") satir = f"{ad:>15s}" for s in (3, 6, 12): d, b, z = olc(liste, s) satir += f" {f'{d}/{b}/{z}':>12s}" print(satir) print() print(f"{'diyagram':>15s} {'değiştiren: iddia':>18s} {'sessiz':>7s}" f" {'tekrarlayan: iddia':>19s} {'sessiz':>7s}") for ad, yuzeyler in DIYAGRAM.items(): d1 = gorselle(A, yuzeyler, "değiştiren") d2 = gorselle(A, yuzeyler, "tekrarlayan") print(f"{ad:>15s} {len(d1):18d} {olc(d1, 12)[2]:7d}" f" {len(d2):19d} {olc(d2, 12)[2]:7d}") ``` ``` iddia 56 | metinde örneğe gömülü 17 | tümü diyagrama taşınsa gömülü 0 diyagram yüzey iddia metinde gömülü ilk yanlış sürüm kavram şeması kavram 11 0 12 bileşen şeması ad 7 3 5 akış şeması akis 16 9 3 arayüz şeması imza 22 5 2 karma şema imza+akis+ad 45 17 2 diyagram metni değiştirdiğinde — doğru/bayat/sessiz diyagram sürüm 3 sürüm 6 sürüm 12 diyagramsız 18/38/24 11/45/28 0/56/39 kavram şeması 18/38/24 11/45/28 0/56/39 bileşen şeması 18/38/24 11/45/31 0/56/42 akış şeması 18/38/33 11/45/37 0/56/48 arayüz şeması 18/38/29 11/45/33 0/56/44 karma şema 18/38/38 11/45/45 0/56/56 diyagram değiştiren: iddia sessiz tekrarlayan: iddia sessiz kavram şeması 56 39 67 50 bileşen şeması 56 42 63 46 akış şeması 56 48 72 55 arayüz şeması 56 44 78 61 karma şema 56 56 101 84 ``` #### Altı Kat Farklı Ömür İlk tablonun son sütunu dersin en kısa sonucudur: **12, 5, 3, 2, 2**. Aynı çizim emeği, aynı sayfa, aynı okur — ve resmin doğru kalma süresi altı kat değişiyor. Belirleyen şey resmin güzelliği, aracın niteliği ya da ayrıntı düzeyi değil; **neyi gösterdiğidir**. Kavram şeması on ikinci sürüme kadar doğru kalır çünkü bir kısıtın bir kararı nasıl doğurduğu ürünün alan adlarından, çağrı biçimlerinden ve adım sırasından bağımsızdır; o resim ancak kararın kendisi değişince yanlışlaşır. Arayüz şeması ikinci sürümde yanlışlaşır çünkü gösterdiği şey her iki sürümde bir değişir. Kursun ikinci iddiası burada bir kez daha geçerlidir: **bayatlama hızını biçim değil, bağlanılan yüzey belirler.** Karma şema satırı bu yüzden en pahalı seçimdir. **45** iddia taşır, yani dokümanın büyük bölümünü resme çevirir ve **2**'nci sürümde bütün olarak yanlışlaşır — içindeki tek bir imza değiştiği anda okur resmin hangi bölümüne güveneceğini bilemez. Bir diyagramın "her şeyi bir arada göstermesi" bir erdem değil, **ömrünü en hızlı bileşenine bağlamaktır**. Ortadaki sütun ikinci maliyeti veriyor. Kavram şeması metinden **0** gömülü iddia alır; zaten kavram iddiaları hiçbir zaman örneğe gömülemezdi. Akış şeması ise **9**, arayüz şeması **5**, karma şema **17** gömülü iddiayı metinden alıp resme taşır. Bu iddialar taşındıkları anda sınanabilirliklerini yitirir. #### Sessizleşen Doküman İkinci tablo bu kaybı doküman düzeyinde gösteriyor ve önce bir şeyin **değişmediğini** söylüyor: doğru ve bayat sütunları bütün satırlarda aynı. Üçüncü sürümde **18/38**, altıncıda **11/45**, on ikincide **0/56**. Diyagram hiçbir iddianın ömrünü uzatmaz ya da kısaltmaz; diyagram bir bakım aracı değildir. Değişen tek şey üçüncü sayıdır. Diyagramsız dokümanda on ikinci sürümde **39** sessiz iddia vardır. Kavram şeması bu sayıyı **değiştirmez** — resim hiçbir sesi susturmamıştır, çünkü zaten sessiz olan iddiaları almıştır. Bileşen şeması **42**'ye, arayüz şeması **44**'e, akış şeması **48**'e çıkarır. Karma şema **56**'ya çıkarır: on ikinci sürümde dokümanın **bütün** iddiaları bayattır ve **hiçbiri** ses çıkarmamaktadır. Üçüncü sürüm sütunu daha erken bir uyarı veriyor. Akış şeması daha üçüncü sürümde sessiz sayısını 24'ten **33**'e çıkarıyor; akış yüzeyi tam o sürümde değişir ve resme taşınmış dokuz gömülü iddia tam o anda susmuş olur. Görselin bedeli en çok, **en sık değişen yüzeyde** ödenir. Karar bu iki tablodan doğrudan çıkar. **Çizilecek şey, örneğe gömülemeyen şeydir.** Kavram iddiaları zaten sınanamaz; onları resme taşımak bedava bir kazançtır — hem uzun ömürlüdür hem hiçbir sesi susturmaz. Akış ve imza iddiaları ise dokümanın ses çıkaran bölümüdür; onları resme taşımak, çalışan bir sınamayı silmekle aynı şeydir. #### Resmin Kaynağı Metinse Yukarıdaki ölçüm iki ayrı sakıncayı birlikte saydı: diyagram **çalıştırılamaz** ve **taranamaz**. Bunlardan yalnız biri diyagramın doğasından gelir. İkincisi bir **saklama biçimi** kararıdır ve geri alınabilir. Bir diyagram iki biçimde saklanabilir. Ya bir resim dosyası olarak durur — içine tarama giremez, iki sürümü arasında fark alınamaz, inceleme sırasında neyin değiştiği okunamaz. Ya da kaynağı metin olarak durur ve resim kurma sırasında üretilir. ```text # ornek diyagram kaynagi , calistirilmamistir , yalnizca bicimi gosterir kaynağı metin olan kavram şeması düğüm ölçüm-kuyruğu "sıra korunmak zorunda" düğüm yazan-uç "aynı anda tek yazan" bağ ölçüm-kuyruğu -> yazan-uç "sıra kısıtı buradan doğuyor" resim dosyası olarak saklanan aynı şema (ikili içerik; tarama giremez, fark alınamaz, inceleme okuyamaz) ``` Kaynağı metin olan biçimde üçüncü dersin yeniden adlandırma taraması resmin içine girer: `ölçüm-kuyruğu` adı değiştiğinde tarama onu tıpkı bir paragraftaki gibi bulur. Diyagram böylece "kaçınılmaz kaçan" sınıfından çıkar ve bakımı ölçülebilir hâle gelir. Bu kazancın sınırı da nettir ve abartılmamalıdır. Kaynağın metin olması diyagramı **gömülü yapmaz**: kaynak çalıştırılmaz, yalnız çizilir; hiçbir sınama şemanın artık var olmayan bir bağı gösterdiğini bildirmez. Bayatlama hızı da değişmez — resim hangi yüzeye bağlıysa o sıklıkta yanlışlaşır. Yani ikinci tablonun sessizlik sütunu bu kararla **kıpırdamaz**. Kazanılan tek şey, sessiz bayatlamanın bir denetimle **bulunabilir** olmasıdır; kendiliğinden duyulur olması değil. #### Değiştiren ve Tekrarlayan Son tablo ikinci bir kararı ölçüyor: diyagram metnin **yerine mi** geçiyor, yanına mı ekleniyor? İkinci durum yaygındır ve zararsız görünür — aynı şey hem yazılmış hem çizilmiştir, okur hangisini isterse onu kullanır. Sayılar zararsız olmadığını söylüyor. Tekrarlayan kipte doküman **56** iddiadan **63** ile **101** arasında bir yere çıkıyor ve **hiçbir yeni bilgi eklenmiyor**; eklenen iddiaların hepsi metinde zaten yazılı olanların kopyası. Karşılığında on ikinci sürümde sessiz iddia sayısı, arayüz şemasında 44'ten **61**'e, karma şemada 56'dan **84**'e çıkıyor. Bunun nedeni üçüncü dersin ölçtüğü şeyle aynıdır. Kopya, kaynağıyla birlikte güncellenmez. Metin düzeltilir, resim eski hâliyle kalır ve bu kez okurun elinde birbiriyle çelişen iki kaynak vardır. Hangisinin yeni olduğunu söyleyen bir şey yoktur; resimde tarih yazmaz. Kural bu yüzden tek cümleyle söylenebilir: **diyagram metne hizmet ediyorsa metnin yerini alır, etmiyorsa yalnız bakım borcu ekler.** Bir resim, yanındaki paragrafın söylediğini söylüyorsa ikisinden biri fazladır ve fazlalık olan taraf, güncellenmesi unutulan taraftır. #### Özet - Diyagram bir iddia kümesidir ve iddiaları tıpkı cümleler gibi bir yüzeye bağlanır; ayıran yanı, taşıdığı hiçbir iddianın **çalıştırılamaması** ve metin taramasının içine girememesidir. - Bayatlama hızını çizim değil yüzey belirler: kavram şeması **12**, bileşen şeması **5**, akış şeması **3**, arayüz şeması **2** sürümde yanlışlaşır. Birden çok yüzey gösteren resim **en hızlı yüzeyinin** hızıyla bayatlar. - Diyagram hiçbir iddianın ömrünü değiştirmez: doğru ve bayat sayıları bütün seçimlerde aynıdır (**18/38**, **11/45**, **0/56**). Değişen tek şey kaç bayatın **duyulduğudur**. - Metinden resme taşınan gömülü iddia sesini yitirir: on ikinci sürümde sessiz sayısı 39'dan akış şemasında **48**'e, karma şemada **56**'ya çıkar — dokümanın tamamı sessizleşir. - Çizilecek şey, örneğe gömülemeyen şeydir: kavram şeması sessiz sayısını **hiç artırmaz**. Tekrarlayan diyagram ise yeni bilgi eklemeden iddia sayısını **101**'e kadar büyütür ve sessizi **84**'e çıkarır. #### Sonraki Adım Bu konu boyunca doküman hep **yazıldığı andaki hâliyle** ölçüldü: okur tanımı yazılmış mı, başlıklar kaç adım kısaltıyor, terim tek mi, örnek çalışır mı, resim neye bağlı. Beş ölçümün hepsi yazma masasında verilen kararlardı ve hepsi bir kez veriliyordu. Oysa bütün ölçümlerin ikinci ekseni sürümdü. Doküman yazıldığı anda **0/56** bayat, on ikinci sürümde **56/56**; aradaki fark yazma kararlarıyla değil, geçen zamanla geliyor. Öyleyse doküman yazılıp bitirilen bir şey değil, **yaşayan** bir şeydir. Sonraki konu bunu kurar: doküman kodun yanında nasıl sürümlenir, incelemeye nasıl girer, bayatlaması nasıl denetlenir ve sessiz kalan o iddialar hangi döngüyle görünür hâle gelir. ## Doküman İşletimi Dokümanı sürümleme ve inceleme sürecine dahil etme, kaynaktan referans üretme yaklaşımları, eskiyen içeriğin tespiti ve yaşam döngüsü, ve destek taleplerinden doküman eksiği çıkarma. ### Kod ile Birlikte Doküman Source: https://academia.sh/tr/kurslar/teknik-yazarlik/kod-ile-birlikte-dokuman 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. ### Doküman Üretim Yaklaşımları Source: https://academia.sh/tr/kurslar/teknik-yazarlik/dokuman-uretim-araclari Üretim tek bir şey değildir: işaretleme dilinden üretim hiçbir yüzeyi kurtarmaz, kaynaktan üretim on ikinci sürümde 22 iddiayı doğru tutar ve ad ile akış yüzeyindeki 23 iddiaya dokunamaz. Önceki ders incelemenin borcu yedi kat düşürdüğünü gösterdi, ama bu kazancın bedeli bir insanın her değişiklikte doküman satırlarını da okumasıdır. Okuyan insan pahalıdır ve dikkati sabit değildir. Bir yüzey için daha ucuz bir yol vardır: iddiayı elle yazmak yerine **bağlandığı kaynaktan üretmek**. Üretilen bir iddia, kaynağı değiştiğinde kendiliğinden değişir. Kimse onu hatırlamak zorunda değildir, kimse onu incelemek zorunda değildir; bayatlaması düşünülemez hâle gelir. Bu dersin sorusu bunun ne kadarına yettiğidir. Elli altı iddianın kaçı bir kaynaktan okunabilir, kaçı okunamaz ve okunamayanlar hangi yüzeydedir? Ölçüm üç üretim yaklaşımını elle yazılan dokümanla yan yana koyar ve dördünü aynı on iki sürüm boyunca izler. #### İddianın Kaynağı Bir iddianın **kaynağı**, doğruluğunu belirleyen yerdir. "Bu alanın türü tam sayıdır" cümlesinin kaynağı, alanın tanımlandığı satırdır. "Önce ölçüm oluşturulur, sonra gönderilir" cümlesinin kaynağı, bu sırayı zorunlu kılan işleyiştir. "Bu yapıya birim denir" cümlesinin kaynağı, adı veren karardır. "Birim alanı zorunlu tutulur, çünkü ölçümler birimsiz karşılaştırılamaz" cümlesinin kaynağı, gerekçenin kendisidir. Aradaki fark şudur: **birinci kaynak makine tarafından okunabilir, diğer üçü okunamaz.** Bir alanın türü kaynağın içinde yazılıdır ve oradan çekilebilir. Adımların sırası, bir şeyin adı ve bir kararın gerekçesi kaynağın içinde bir yerde durmaz; onları yalnız bir insan bilir. Üretim bu ayrımın üstüne kurulur ve bu ayrım üretimin sınırıdır. #### Üç Yaklaşım Sınıfı Yaklaşımlar ürün adlarıyla değil, **sınıf adlarıyla** anılır; ürünler değişir, sınıflar kalır. **İşaretleme dilinden üretim.** Doküman bir işaretleme dilinde yazılır ve bir çevirici onu yayımlanabilir bir biçime dönüştürür. Bağlantılar denetlenir, içindekiler listesi çıkarılır, sayfa düzeni uygulanır. Üretilen şey **biçimdir**. Metnin iddiaları yazıldığı gibi durur ve kaynağa hiç bakılmaz. **Açıklama satırından üretim.** İddialar kaynağın içine, tanımladıkları öğenin hemen yanına yazılır; bir araç bunları toplayıp doküman hâline getirir. Toplanan metnin bir bölümü elle yazılmıştır, bir bölümü tanımın kendisinden okunur: parametrenin adı, türü, dönüş değeri. Kapsamı dardır — kaynağın yanında yalnızca kaynağı anlatan metin durabilir. Bir öğretici ya da bir gerekçe oraya sığmaz. **Kaynaktan üretim.** Arayüzün tanımı doğrudan okunur ve referans metni ondan üretilir. Kapsam geniştir: hangi türde doküman olursa olsun, içindeki imza iddiaları kaynaktan gelebilir. Bu yolla elde edilen metin **üretilen referans (generated reference)** adını alır. Üretilmiş bir parçanın nasıl göründüğü aşağıdadır. Kurgu bir ürüne aittir ve çalıştırılmamıştır: ```text # uretilmis referans parcasi , ornek dokum , calistirilmamistir olcum_gonder(deger, birim, kaynak=None) deger ondalık zorunlu birim metin zorunlu kaynak metin veya boş varsayılan: boş döndürür: kayıt kimliği (metin) ``` Bu parçadaki her satır tanımdan okunmuştur. Alan eklenirse satır eklenir, tür değişirse sütun değişir. Parçanın söylemediği de aynı ölçüde belirgindir: `birim` alanının neden zorunlu olduğu, hangi sırayla çağrılacağı ve bu işleve verilen adın nereden geldiği üretilemez. Üretilen metnin bir özelliği daha vardır ve ölçüme girmez: **sırası okurun değil, kaynağın sırasıdır.** Alanlar tanımlandıkları düzende listelenir, işlevler kaynaktaki yerlerine göre dizilir. Yazım Disiplini konusunda ölçülen taranabilirlik düzeni burada kurulmaz, çünkü üretimi yapan araç okurun hangi soruyla geldiğini bilmez. Bu, üretilen referansın eksikliği değil tanımıdır: eksiksizliği kaynaktan gelir, düzeni gelmez. Bir dokümanın üretilen bölümleriyle elle yazılan bölümleri bu yüzden birbirinin yerine geçmez; biri her zaman doğru ve düzensiz, öbürü düzenli ve bayatlayabilirdir. #### Ölçümün Varsayımları - **DI11** — Elli altı iddia, dört tür ve dört yüzey ortak kurgudan alınır; yüzey sıklıkları değişmez. Kâhin kurgunun kendisidir. - **DI12** — Bir yaklaşım iki şeyle tanımlanır: **kapsadığı türler** ve **kaynaktan okuduğu yüzey**. Kapsam içindeki bir türün, okunan yüzeye bağlı iddiaları hiç bayatlamaz. - **DI13** — İşaretleme dilinden üretim dört türü de kapsar ve **hiçbir yüzeyi** kaynaktan okumaz; ürettiği şey biçimdir. - **DI14** — Açıklama satırından üretim yalnız **referans** türünü kapsar ve **imza** yüzeyini kaynaktan okur; kaynağın yanına öğretici, açıklama ya da nasıl yapılır metni konmaz. - **DI15** — Kaynaktan üretim dört türü de kapsar ve **imza** yüzeyini kaynaktan okur; hangi türde olursa olsun bir imza iddiası tanımdan üretilebilir. - **DI16** — Hiçbir yaklaşım ad, akış ve kavram yüzeyini okuyamaz; bu üç yüzeyin kaynağı makine tarafından okunabilir bir yerde durmaz. - **DI17** — Üretim örneğe gömülülüğü değiştirmez. Gömülü iddia bayatlayınca ses çıkarır, gömülü olmayan çıkarmaz; **sessiz bayatlama** tanımı ortak kurgudaki hâliyle kalır. - **DI18** — Ölçüm üretimin kurulum ve işletim maliyetini saymaz; yalnız sürüm başına doğru kalan, bayatlayan ve sessizce bayatlayan iddia sayısını verir. #### Ölçüm ```python """Uretim yaklasimlarinin kurtardigi ve kurtaramadigi yuzey. Bolum 1 - dort yaklasim, alti surumde dogru/bayat/sessiz. Bolum 2 - kaynaktan uretimin tur basina kazanci ve yuzey basina siniri. """ 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} SURUMLER = (0, 1, 2, 3, 6, 12) DORDU = ("öğretici", "nasıl yapılır", "açıklama", "referans") # yaklasim: (kapsadigi turler, kaynaktan okunan yuzey) YAKLASIM = {"elle yazılan": ((), None), "işaretlemeden": (DORDU, None), "açıklamadan": (("referans",), "imza"), "kaynaktan": (DORDU, "imza")} 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 bayat_mi(iddia, surum, yaklasim): kapsam, okunan = YAKLASIM[yaklasim] if iddia["tur"] in kapsam and iddia["yuzey"] == okunan: return False return surum // SIKLIK[iddia["yuzey"]] >= 1 def olc(liste, surum, yaklasim, tur=None): grup = [i for i in liste if tur is None or i["tur"] == tur] bayat = [i for i in grup if bayat_mi(i, surum, yaklasim)] 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"iddia {len(L)}, imza yüzeyine bağlı " f"{sum(1 for i in L if i['yuzey'] == 'imza')}, kalan " f"{sum(1 for i in L if i['yuzey'] != 'imza')}") print() print(f"{'sürüm':>6s}" + "".join(f" {y:>18s}" for y in YAKLASIM)) print(f"{'':6s}" + "".join(f" {'doğru/bayat/sessiz':>18s}" for _ in YAKLASIM)) for s in SURUMLER: satir = f"{s:6d}" for yaklasim in YAKLASIM: _, dogru, bayat, sessiz = olc(L, s, yaklasim) satir += f" {f'{dogru}/{bayat}/{sessiz}':>18s}" print(satir) print() print(f"{'tür':>15s} {'iddia':>6s} {'imza':>5s} {'elle 6':>7s} " f"{'kaynaktan 6':>12s} {'elle 12':>8s} {'kaynaktan 12':>13s}") for tur in TURLER: imza = sum(1 for i in L if i["tur"] == tur and i["yuzey"] == "imza") t, e6, _, _ = olc(L, 6, "elle yazılan", tur) _, k6, _, _ = olc(L, 6, "kaynaktan", tur) _, e12, _, _ = olc(L, 12, "elle yazılan", tur) _, k12, _, _ = olc(L, 12, "kaynaktan", tur) print(f"{tur:>15s} {t:6d} {imza:5d} {f'{e6}/{t}':>7s} {f'{k6}/{t}':>12s} " f"{f'{e12}/{t}':>8s} {f'{k12}/{t}':>13s}") print() print(f"{'yüzey':>7s} {'iddia':>6s} {'kaynaktan okunur':>17s} " f"{'12. sürümde doğru':>18s}") for y in SIKLIK: g = [i for i in L if i["yuzey"] == y] dogru = sum(1 for i in g if not bayat_mi(i, 12, "kaynaktan")) print(f"{y:>7s} {len(g):6d} {'evet' if y == 'imza' else 'hayır':>17s} " f"{dogru:18d}") ``` ``` iddia 56, imza yüzeyine bağlı 22, kalan 34 sürüm elle yazılan işaretlemeden açıklamadan kaynaktan doğru/bayat/sessiz doğru/bayat/sessiz doğru/bayat/sessiz doğru/bayat/sessiz 0 56/0/0 56/0/0 56/0/0 56/0/0 1 56/0/0 56/0/0 56/0/0 56/0/0 2 34/22/17 34/22/17 47/9/4 56/0/0 3 18/38/24 18/38/24 31/25/11 40/16/7 6 11/45/28 11/45/28 24/32/15 33/23/11 12 0/56/39 0/56/39 13/43/26 22/34/22 tür iddia imza elle 6 kaynaktan 6 elle 12 kaynaktan 12 öğretici 15 3 1/15 4/15 0/15 3/15 nasıl yapılır 14 5 1/14 6/14 0/14 5/14 açıklama 12 1 9/12 10/12 0/12 1/12 referans 15 13 0/15 13/15 0/15 13/15 yüzey iddia kaynaktan okunur 12. sürümde doğru imza 22 evet 22 akis 16 hayır 0 ad 7 hayır 0 kavram 11 hayır 0 ``` Sütun başlıklarındaki kısaltmalar yaklaşım sınıflarının adlarıdır: işaretleme dilinden üretim, açıklama satırından üretim ve kaynaktan üretim. #### İlk İki Satır Aynıdır Tablonun en çabuk okunan bulgusu ilk iki satırın **birebir aynı** olmasıdır. Elle yazılan doküman ile işaretleme dilinden üretilen doküman, altı sürümün altısında da aynı üçlüyü verir: on ikinci sürümde ikisi de **0/56/39**. Bunun nedeni tanımdadır. İşaretleme dilinden üretim iddiaların kaynağına hiç bakmaz; metin neyi söylüyorsa onu daha düzgün bir biçimde gösterir. Yayım işini otomatikleştirmek gerçek bir kazançtır — bağlantılar denetlenir, sürüm ayrımı kurulur, biçim birliği sağlanır — ama **doğrulukla ilgisi yoktur**. Bir aracın "doküman üretiyor" olması, ürettiği şeyin iddiaları olduğu anlamına gelmez. Üretim sözcüğü bu iki işi aynı adla anar ve tabloda aralarında elli altı iddialık bir fark vardır. Bir kurulumu değerlendirirken sorulacak soru aracın ne ürettiği değil, **hangi yüzeyi hangi kaynaktan okuduğudur**; bu soruya "hiçbirini" yanıtı geliyorsa üretilen şey yalnızca biçimdir. #### Kaynaktan Üretimin Kurtardığı Dördüncü sütun ikinci sürümde **56/0/0** verir; elle yazılan aynı sürümde **34/22/17** vermiştir. İlk çatlak ancak üçüncü sürümde, akış yüzeyi değiştiğinde açılır. On ikinci sürümde kaynaktan üretim **22** doğru iddia bırakır — elle yazılanın **0**'ına karşılık. Yirmi iki sayısı doğrudan okunabilir: imza yüzeyine bağlı iddia sayısıdır. Alt tablo bunu tek tek gösterir. İmza satırında on ikinci sürümde doğru kalan **22**, yani hepsi; öbür üç satırda **0**. Kaynaktan üretim bir yüzeyi tümüyle kaldırır ve öbür üçüne dokunmaz. Aradaki oran ölçünün en kısa özetidir: **elli altı iddianın 22'si üretilebilir, 34'ü üretilemez.** Açıklama satırından üretim aynı yüzeyi okur ama yalnız bir türü kapsar; on ikinci sürümde **13** doğru iddia bırakır. On üç, referans türündeki imza iddialarının sayısıdır. Aradaki dokuz iddialık fark, öbür üç türün içindeki imza iddialarıdır ve bunlar kaynağın yanına sığmaz — bir öğreticinin ortasındaki çağrı örneği kaynağın açıklama satırında duramaz. #### Kurtarılamayan İki Yüzey Kaynaktan üretimin on ikinci sürümdeki **34** bayat iddiasının dağılımı şudur: akış **16**, kavram **11**, ad **7**. Kursun beşinci okuması bu üçlünün ikisini öne çıkarır, çünkü ikisi referans türünün içinde de görünür: **ad** ve **akış**. Bu iki yüzey neden üretilemez? **Ad**, bir şeyin dışarıya verilen adıdır ve kaynaktaki tanımlayıcıyla aynı olmak zorunda değildir. Kaynakta `olcum_gonder` yazması, dokümanda "ölçüm gönderme" mi yoksa "kayıt oluşturma" mı denmesi gerektiğini söylemez; ad kararı kaynağın dışındadır ve değiştiğinde kaynakta hiçbir iz bırakmaz. **Akış**, adımların sırasıdır ve tek tek imzalardan çıkarılamaz. Üç işlevin tanımı da doğru üretilir, hangisinin önce çağrılacağı hiçbirinin tanımında yazmaz. Alt tablonun ikinci sütunu bu iki yüzeyde **23** iddia sayar. Bunlar üretimin varlığından etkilenmez: kaynaktan üretim kurulmuş bir dokümanda da, kurulmamış bir dokümanda da aynı hızda bayatlarlar. Üretim bu iddiaları **kurtarmaz**, üstelik onları daha da tehlikeli kılar: doküman güncel görünür, imza tabloları tazedir ve aralarındaki akış cümlesi sessizce yanlıştır. #### Türlere Göre Kazanç Orta tablo üretimin kime yaradığını türe göre ayırır. Altıncı sürümde referans elle yazılmış hâlde **0/15** verirken, kaynaktan üretilmiş hâlde **13/15** verir — bu, Doküman Türleri konusunda ölçülen karşılaştırmanın aynısıdır. Öğretici ise **1/15**'ten **4/15**'e çıkar; kazanç üç iddiadır ve on ikinci sürümde de üç kalır. Fark, türlerin yüzey dağılımından gelir. Referansın on beş iddiasının **13**'ü imzaya bağlıdır; öğreticinin on beş iddiasının yalnız **3**'ü. Öğretici öncelikle akış anlatır ve akış üretilemez. Açıklama türünde tablo daha da keskindir: on iki iddianın **1**'i imzaya bağlıdır, on ikinci sürümde kaynaktan üretim **1/12** verir ve kazanç tek bir iddiadır. Buradan çıkan işletim kararı doğrudur ve dar bir kararla sınırlıdır: **üretim, referans türünü hedefler.** Öbür üç tür için üretim kurmak, kurulum bedelini yüzey dağılımının karşılamadığı bir yatırımdır. Aynı emek o türlerde inceleme ve doküman denetimine harcanırsa daha çok iddia doğru kalır. #### Üretimin Sessizliğe Etkisi Son sütunun on ikinci sürümdeki üçlüsü **22/34/22**'dir: otuz dört bayat iddianın yirmi ikisi sessizdir. Elle yazılan dokümanda aynı satır **0/56/39** verir. Üretim yirmi iki bayat iddiayı ortadan kaldırmıştır, ama sessizlerin sayısı otuz dokuzdan yirmi ikiye inerken **gürültü çıkaranların** sayısı da düşer. Hesap kısadır. Yirmi iki imza iddiasının **5**'i çalıştırılabilir örneğe gömülüdür. Üretim bu iddiaları doğru tuttuğu için o beş örnek artık hiç bozulmaz. Geriye kalan otuz dört iddianın gömülü olanı **17 − 5 = 12**'dir. Yani üretim, bayatlamayı haber veren kanalı da daraltır: on yedi uyarı noktasından beşi kapanır. Bu bir kusur değil, bir yer değiştirmedir. Üretimden önce doküman elli altı iddiadan on yedisi için kendi kendine sinyal üretiyordu; sonra otuz dört iddiadan on ikisi için üretir. Her iki durumda da geriye kalanı bulmanın tek yolu birinin oturup **iddiayı kaynağıyla karşılaştırmasıdır**. Üretim bu işi küçültür, ortadan kaldırmaz. #### Özet - Bir iddianın kaynağı makine tarafından okunabiliyorsa üretilebilir; imza böyledir, ad, akış ve kavram değildir. - İşaretleme dilinden üretim biçim üretir, iddia üretmez; tabloda elle yazılan dokümanla **birebir aynı** üçlüleri verir ve on ikinci sürümde ikisi de **0/56/39**'dur. - Kaynaktan üretim on ikinci sürümde **22** iddiayı doğru tutar; bu sayı imza yüzeyine bağlı iddia sayısının tamamıdır. - Açıklama satırından üretim yalnız referans türünü kapsadığı için **13** iddiada kalır; kapsam farkı dokuz iddiadır. - Üretimin kurtaramadığı **34** iddianın **23**'ü ad ve akış yüzeyindedir; doküman güncel görünürken bu iddialar sessizce yanlış olabilir. - Yüzey dağılımı gereği üretim referans türünü hedefler: referans **13/15**, öğretici **3/15**, açıklama **1/12** kazanır. #### Sonraki Adım Elimizde şimdi iki savunma var ve ikisi de kısmi: inceleme ad ile kavramı göremiyor, üretim ad ile akışı üretemiyor. İkisinden de geriye kalan iddialar, yanlış olduklarını hiçbir biçimde duyurmayanlardır. Sonraki ders kursun merkezine iner ve bu artığı sayar: dört türün altı sürüm boyunca doğru, bayat ve sessiz üçlüleri, on ikinci sürümdeki sessizlik oranı ve sessiz olanı bulmak için gereken **doküman denetiminin** iddia başına bedeli. ### Bayatlama ve Doküman Denetimi Source: https://academia.sh/tr/kurslar/teknik-yazarlik/bayatlama-ve-denetim On ikinci sürümde 56 iddianın 56'sı bayattır ve 39'u sessizdir; sessizlik oranı 0,6964'tür ve sessiz olanı bulmak, doküman denetiminin iddia başına ödediği okuma bedeliyle ölçülür. Önceki iki ders iki savunma kurdu ve ikisi de eksik kaldı. İnceleme, ad ve kavram yüzeyindeki iddiaları göremiyor; üretim, ad ve akış yüzeyindeki iddiaları üretemiyor. Her iki savunmadan da geriye, yanlış olduğunu hiçbir biçimde duyurmayan bir artık kalıyor. Bu ders o artığı sayar. Kursun merkez sorusu burada tam olarak sorulur: bir dokümanın iddialarından kaçı zamanla yanlışlaşır ve **yanlışlaşanların kaçı bunu kendiliğinden söyler?** İkinci sayı birincisinden daha önemlidir, çünkü kendini söyleyen yanlış bir sorun değil, bir bildirimdir. Kendini söylemeyen yanlış ise ancak biri onu aramaya çıktığında bulunur — ve bu arama işinin adı **doküman denetimidir**. #### Bayatlamanın İki Türü Ortak kurgunun ayrımı basittir ve kurs boyunca değişmez. Elli altı iddianın **17**'si çalıştırılabilir bir örneğe gömülüdür. Gömülü bir iddia bayatladığında örnek çalışmaz: kopyalayan okur bir hata görür, sürekli tümleştirme hattı örneği çalıştırıyorsa hattın kendisi kırılır. Bu iddia **ses çıkarır**. Kalan **39** iddia düz cümledir. Bir alanın türü, bir adımın sırası, bir şeyin adı, bir kararın gerekçesi — hepsi metnin içinde durur ve yanlışlaştıklarında hiçbir şey olmaz. Sayfa yine açılır, hattan yine geçer, arama yine bulur. Bu **sessiz bayatlamadır** ve kursun ölçüsünün merkezindedir. Ayrımın işletim sonucu şudur: bir dokümanın sağlığı hakkında elinizde iki tür kanıt vardır ve biri ölçülebilir, öbürü ölçülemez. Kırılan örnek sayılabilir. Sessizce yanlış olan cümle sayılamaz — sayılabilseydi zaten düzeltilirdi. **Sessiz bayatlamanın tanımı, kendini saydırmamasıdır.** Ölçüm bunu ancak kurgu bir kâhinle yapabilir: hangi iddianın hangi sürümde bayatladığını biz yazdığımız için biliriz. #### Doküman Denetimi Ne Yapar **Doküman denetimi**, iddiaları tek tek kaynağıyla karşılaştırma işidir. Bir kişi metni okur, her cümlenin hâlâ doğru olup olmadığını kaynağa bakarak doğrular ve yanlış olanı işaretler. Bu işin bedeli okunan iddia sayısıyla ölçülür; kazancı ise bulunan sessiz bayat sayısıdır. Denetimin kapsamı bir seçimdir. Dokümanın tamamı okunabilir ya da yalnız bir türü. Kapsam seçimi doğrudan bir verim sorusudur: **okunan her iddia başına kaç sessiz bayat bulunuyor?** Ses çıkaran iddialar bu hesabın dışındadır — onlar kapsam ne olursa olsun bulunur, çünkü kendilerini bildirmişlerdir. Denetimin çıktısı bir listedir, düzeltme değildir. Kurgu, bulunan bayatın düzeltilip düzeltilmediğini ölçmez; ölçtüğü tek şey **bulunup bulunmadığıdır**. Bulunmayan bir bayat iddiayı düzeltmenin yolu yoktur. ```text # ornek denetim ciktisi , calistirilmamistir referans / olcum_gonder [bayat] kaynak alanı zorunludur -> tanımda varsayılan değer var [bayat] döndürür: kayıt numarası (tam sayı) -> tanımda metin döndürüyor [doğru] birim alanı zorunludur öğretici / ilk ölçüm [bayat] önce oturum açılır, sonra ölçüm gönderilir -> sıra değişmiş ``` Listenin biçimi önemsizdir; önemli olan her satırın bir **iddia** olmasıdır. Doküman denetimi sayfa saymaz, paragraf saymaz, iddia sayar. Ölçünün birimi budur. #### Ölçümün Varsayımları - **DI21** — 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 sürümde bayatladığı bilinir. - **DI22** — 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. Bir iddia, bağlandığı yüzey bu sürüme kadar en az bir kez değiştiyse bayattır. - **DI23** — Elli altı iddianın on yedisi örneğe gömülüdür; gömülü bayat ses çıkarır, gömülü olmayan bayat sessizdir. Gömülülük yüzeyle birlikte belirlenir ve kavram yüzeyinde hiç gömülü iddia yoktur. - **DI24** — Doküman denetimi, kapsamına giren **her** iddiayı okur ve kâhinle karşılaştırır; okuduğu bayatı kaçırmaz. Bu iyimser bir varsayımdır ve denetimin bulabileceğinin üst sınırını verir. - **DI25** — Ses çıkaran bayat, denetim kapsamı ne olursa olsun bulunur; örnek zaten çalışmamaktadır. Denetimin kapsamı yalnız **sessiz** bayatın bulunmasını belirler. - **DI26** — Denetimin bedeli okunan iddia sayısıdır. Verim, **okunan iddia başına bulunan sessiz bayat** oranıdır ve hiçbir iddia okunmadığında tanımsızdır. - **DI27** — Denetim iki sürümde ayrı ayrı çalıştırılır: üçüncü sürümde ve on ikinci sürümde. İkisi arasındaki fark, denetim hedefinin sürüme göre değiştiğini gösterir. - **DI28** — Kümenin çözünürlüğü elli altı iddiada **1/56**'dır; bundan küçük bir fark bu kurguyla savunulamaz. #### Ölçüm ```python """Bayatlama ve dokuman denetimi: sessiz olani bulmanin bedeli. Bolum 1 - alti surumde dort turun dogru/bayat/sessiz uclusu. Bolum 2 - denetim kapsamlari: incelenen iddia basina bulunan sessiz bayat. """ 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} SURUMLER = (0, 1, 2, 3, 6, 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 bayat_mi(iddia, surum): return surum // SIKLIK[iddia["yuzey"]] >= 1 def olc(liste, surum, tur=None): grup = [i for i in liste if tur is None or i["tur"] == tur] 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) def denetim(liste, surum, kapsam): """Kapsam: elle okunan turler. Gomulu bayat kapsam disinda da bulunur.""" okunan = [i for i in liste if i["tur"] in kapsam] bayat = [i for i in liste if bayat_mi(i, surum)] bulunan = [i for i in bayat if i["gomulu"] or i in okunan] sessiz_bulunan = [i for i in bulunan if not i["gomulu"]] kacan = [i for i in bayat if not i["gomulu"] and i not in okunan] return len(okunan), len(bulunan), len(sessiz_bulunan), len(kacan) L = iddialar() print(f"iddia {len(L)}, tür {len(TURLER)}, örneğe gömülü " f"{sum(1 for i in L if i['gomulu'])}") print("yüzey dağılımı: " + ", ".join( f"{y} {sum(1 for i in L if i['yuzey'] == y)}" for y in SIKLIK)) print() print(f"{'sürüm':>6s}" + "".join(f" {t:>18s}" for t in TURLER)) print(f"{'':6s}" + "".join(f" {'doğru/bayat/sessiz':>18s}" for _ in TURLER)) for s in SURUMLER: satir = f"{s:6d}" for tur in TURLER: _, dogru, bayat, sessiz = olc(L, s, tur) satir += f" {f'{dogru}/{bayat}/{sessiz}':>18s}" print(satir) print() for s in (3, 12): _, _, bayat, sessiz = olc(L, s) print(f"{s}. sürümde bayat {bayat}/{len(L)}, sessiz {sessiz} " f"({sessiz / bayat:.4f})") KAPSAMLAR = [("denetim yok", ()), ("yalnız referans", ("referans",)), ("yalnız açıklama", ("açıklama",)), ("yalnız öğretici", ("öğretici",)), ("yalnız nasıl yapılır", ("nasıl yapılır",)), ("dört tür", tuple(TURLER))] for s in (3, 12): print(f"\nsürüm {s}") print(f"{'denetim kapsamı':>21s} {'okunan':>7s} {'bulunan bayat':>14s} " f"{'bulunan sessiz':>15s} {'kaçan sessiz':>13s} {'verim':>7s}") for ad, kapsam in KAPSAMLAR: okunan, bulunan, sessiz_b, kacan = denetim(L, s, kapsam) verim = f"{sessiz_b / okunan:.4f}" if okunan else "—" print(f"{ad:>21s} {okunan:7d} {bulunan:14d} {sessiz_b:15d} " f"{kacan:13d} {verim:>7s}") ``` ``` iddia 56, tür 4, örneğe gömülü 17 yüzey dağılımı: imza 22, akis 16, ad 7, kavram 11 sürüm öğretici nasıl yapılır açıklama referans doğru/bayat/sessiz doğru/bayat/sessiz doğru/bayat/sessiz doğru/bayat/sessiz 0 15/0/0 14/0/0 12/0/0 15/0/0 1 15/0/0 14/0/0 12/0/0 15/0/0 2 12/3/1 9/5/2 11/1/1 2/13/13 3 3/12/5 3/11/4 10/2/2 2/13/13 6 1/14/6 1/13/4 9/3/3 0/15/15 12 0/15/7 0/14/5 0/12/12 0/15/15 3. sürümde bayat 38/56, sessiz 24 (0.6316) 12. sürümde bayat 56/56, sessiz 39 (0.6964) sürüm 3 denetim kapsamı okunan bulunan bayat bulunan sessiz kaçan sessiz verim denetim yok 0 14 0 24 — yalnız referans 15 27 13 11 0.8667 yalnız açıklama 12 16 2 22 0.1667 yalnız öğretici 15 19 5 19 0.3333 yalnız nasıl yapılır 14 18 4 20 0.2857 dört tür 56 38 24 0 0.4286 sürüm 12 denetim kapsamı okunan bulunan bayat bulunan sessiz kaçan sessiz verim denetim yok 0 17 0 39 — yalnız referans 15 32 15 24 1.0000 yalnız açıklama 12 29 12 27 1.0000 yalnız öğretici 15 24 7 32 0.4667 yalnız nasıl yapılır 14 22 5 34 0.3571 dört tür 56 56 39 0 0.6964 ``` #### Üst Tablo: Dört Tür, Altı Sürüm Birinci ve sıfırıncı sürüm boştur; hiçbir yüzey henüz değişmemiştir ve dört tür de bütün iddialarını korur. İkinci sürümde imza değişir ve tablo hemen ayrışır: referans **2/13/13** verirken açıklama **11/1/1** verir. Aynı sürümde, aynı depoda, aynı özenle yazılmış iki metin; biri iddialarının yüzde on üçünü korumuş, öbürü yüzde doksan ikisini. Fark yazımdan değil, **bağlanılan yüzeyden** gelir. Üçüncü sürümde akış yüzeyi değişir ve bu kez öğretici ile nasıl yapılır çöker: **3/12/5** ve **3/11/4**. Açıklama **10/2/2** ile ayakta kalır, çünkü iddialarının dokuzu kavrama bağlıdır ve kavram on ikide bir değişir. Altıncı sürümde ad yüzeyi de dönmüştür; on ikinci sürümde kavram da döner ve dört türün tamamı sıfırlanır: **56/56**. Bayat sayısının tümü aynı ağırlıkta değildir. Üçüncü sürümde bayat **38**, sessiz **24**; oran **0,6316**. On ikinci sürümde bayat **56**, sessiz **39**; oran **0,6964**. İkinci sayı kursun bağlayıcı sonucudur: **bayatlamanın yaklaşık yüzde yetmişi sessizdir.** Oranın sürümle birlikte yükselmesi rastlantı değildir. Gömülü iddialar imza ve akış yüzeylerinde yoğunlaşır ve bu iki yüzey erken değişir; onların bayatlaması ilk sürümlerde gerçekleşir ve **ses çıkarır**. Ad ve kavram geç değişir, gömülü iddia içermez ve bayatlamaları sessiz olur. Zaman geçtikçe sessizlerin payı artar. **Bir doküman yaşlandıkça yalnız daha yanlış olmaz, aynı zamanda daha sessiz yanlış olur.** Bu yükselişin ölçülebilir olup olmadığı ayrıca sorulmalıdır. Kümenin çözünürlüğü elli altı iddiada **1/56**, yani **0,0179**'dur; bundan küçük bir fark bu kurguyla savunulamaz. İki oran arasındaki fark **0,6964 − 0,6316 = 0,0648**'dir, çözünürlüğün üç katından fazla. Yükseliş ölçüm bandının içindedir. Buna karşılık, iki sürüm arasında yarım iddialık bir kayma gözlemlemek bu kümeyle olanaksızdır; kurgu daha ince ayrımlar için kurulmamıştır. #### Alt Tablolar: Denetimin Verimi `denetim yok` satırı temel çizgidir. Üçüncü sürümde hiç kimse hiçbir şey okumadan **14** bayat iddia bulunur ve **24** sessiz kaçar; on ikinci sürümde **17** bulunur ve **39** kaçar. Bulunan sayı, gömülü iddiaların çalışmayan örnekleridir. Bu, dokümanın kendiliğinden verdiği tek geri bildirimdir ve elli altı iddianın yaklaşık üçte biriyle sınırlıdır. Kapsam satırları denetimin nereye yöneltileceğini gösterir. Üçüncü sürümde **yalnız referans** okumak on beş iddia karşılığında **13** sessiz bayat bulur; verim **0,8667**. Aynı sürümde **yalnız açıklama** okumak on iki iddia karşılığında **2** bulur; verim **0,1667**. Aradaki fark beş kattan fazladır ve denetimi yapan kişinin harcadığı emek neredeyse aynıdır. On ikinci sürümde tablo düzleşir. Referans ve açıklama **1,0000** verir: okunan her iddia bir sessiz bayattır, çünkü ikisinde de gömülü iddia yoktur ve her şey bayatlamıştır. Öğretici **0,4667**, nasıl yapılır **0,3571** verir; bu iki türde okunan iddiaların bir bölümü gömülüdür ve zaten bulunmuştu — denetim onlar için boşa okumuş olur. Buradan iki işletim kuralı çıkar. Birincisi: **denetim hedefi tür değil, yüzeydir.** Referansın erken verimli olması yazım biçiminden değil, iddialarının on üçünün imzaya bağlı olmasından gelir. İkincisi: **gömülü iddiası çok olan tür, denetim için kötü bir hedeftir.** Orada bayatlama zaten kendini bildirir; denetimin okuma emeği kendini bildirmeyene ayrılmalıdır. Tam kapsam satırı iki sayıyla kapanır. Üçüncü sürümde elli altı iddianın hepsini okumak **24** sessiz bayat bulur ve verim **0,4286**'dır; on ikinci sürümde **39** bulur ve verim **0,6964**'tür. Bu ikinci sayı üst tablodaki sessizlik oranıyla aynıdır ve tanım gereği öyledir: tam kapsamlı bir doküman denetiminin verimi, o dokümandaki sessiz bayatlama oranının kendisidir. **Denetim ne kadar iyi yapılırsa yapılsın, bulacağı şeyin sınırı dokümanın kaç iddiasının sessizce yanlış olduğudur.** #### Denetimi Ne Tetikler Denetimin verimini kapsam belirliyorsa, kapsamı da bir şeyin belirlemesi gerekir. Takvim kötü bir belirleyicidir: üç ayda bir yapılan bir denetim, hangi yüzeyin değiştiğinden bağımsız olarak aynı iddiaları okur ve emeğin bir bölümü hiç değişmemiş cümlelere gider. Daha iyi bir belirleyici deponun kendi kaydıdır. Bir yüzeyin değiştiği, o değişikliği yapan kaydın içinde yazılıdır: bir alan eklendiğinde imza değişmiştir, bir adım eklendiğinde akış değişmiştir. **Sürüm Kontrolüne Giriş** kursu bu kaydın nasıl okunacağını kurdu ve **Dallanma ve İşbirliği** kursu tarihçenin hangi soruları yanıtlayabildiğini ölçtü. Buradaki kullanım dardır: tarihçe, denetimin **hangi yüzeye** yöneltileceğini söyler. Bu yöntemin bir sınırı vardır ve kurs boyunca ikinci kez karşımıza çıkar. Tarihçe, kod değiştiğinde iz taşır; **ad ve kavram yüzeyleri kodun dışında değişir**. Bir ürün adının değiştiğine ya da bir gerekçenin geçersizleştiğine dair tarihçede hiçbir kayıt olmayabilir. On ikinci sürümde bu iki yüzeyde **18** iddia durur ve hepsi bayattır. Tarihçeyle tetiklenen bir denetim onları hiç aramaz; onlar için tetiği çekecek başka bir kaynak gerekir. #### Özet - Bayatlamanın iki türü vardır: örneğe gömülü iddia bayatladığında ses çıkarır, gömülü olmayan iddia sessizce bayatlar ve hiçbir belirti vermez. - İkinci sürümde referans **2/13/13**, açıklama **11/1/1** verir; aynı özenle yazılmış iki metnin ömrünü belirleyen şey bağlandıkları yüzeydir. - On ikinci sürümde elli altı iddianın **56**'sı bayattır ve **39**'u sessizdir; oran **0,6964**'tür ve üçüncü sürümdeki **0,6316**'dan yüksektir. - Doküman denetimi olmadan yalnız gömülü bayatlar bulunur: on ikinci sürümde **17** bulunur, **39** kaçar. - Denetimin verimi kapsamla değişir: üçüncü sürümde yalnız referans okumak **0,8667**, yalnız açıklama okumak **0,1667** verir; hedef tür değil yüzeydir. - Tam kapsamlı denetimin verimi, dokümanın sessizlik oranının kendisidir — on ikinci sürümde **0,6964**. #### Sonraki Adım Doküman denetimi sessiz bayatı bulur, ama birinin oturup elli altı iddiayı okumasını gerektirir ve bu iş kimsenin takviminde kendiliğinden yer almaz. Denetim yapılmadığı sürece o otuz dokuz iddia yerinde durur ve her gün birileri onları okur. Sonraki ders o okurlara bakar: yanlış bir cümleye çarpan okur ne yapar, kaçı bunu bildirir ve kaç ziyaretten sonra sessiz bayatların kaçı görünür hâle gelir. Kursun son dersi, üçüncü iddianın tek panzehiri olan **geri bildirim döngüsünü** ölçer. ### Geri Bildirim Döngüsü Source: https://academia.sh/tr/kurslar/teknik-yazarlik/geri-bildirim-dongusu Sessiz bayatlama ancak okur bildirdiğinde görünür: 240 ziyaret 39 sessiz iddianın 31'ini açığa çıkarır, 39'unun tamamı için 960 ziyaret gerekir ve bildirim başına bedel 5,0'dan 24,6 ziyarete yükselir. Önceki ders doküman denetiminin sessiz bayatı bulduğunu gösterdi: elli altı iddianın hepsi okunursa otuz dokuzunun da yanlış olduğu görülür. Denetimin sorunu bulamaması değil, **başlamamasıdır**. Kimsenin takviminde kendiliğinden yer almaz ve yapılmadığı sürece o otuz dokuz iddia yerinde durur. Ama bu süre boyunca doküman okunmaya devam eder. Her gün birileri onu açar, bir cümleyi okur, ona göre davranır ve yanılır. Bu dersin sorusu şudur: **okur, denetimin yapmadığı işi ne kadar yapar?** Sessiz bayatlamanın tek doğal düşmanı, ona çarpan ve bunu söyleyen kişidir. Ölçüm o kişilerin kaçının gerektiğini sayar. #### Okurun Çarptığı İddia Bir okur dokümana bir soruyla gelir ve bir iddiaya çarpar. Üç durum olabilir. İddia doğruysa okur işini yapar ve geri bildirim üretmez. İddia bayatsa ve örneğe gömülüyse okur bir hata görür: örnek çalışmaz, ekranda bir arıza vardır ve okur bunu bir arıza olarak bildirir. İddia bayatsa ve sessizse okur bir arıza görmez — dokümanda yazanı yapar, beklediği sonucu alamaz ve **ne olduğunu bilmez**. Üçüncü durumun kritik yanı, okurun kendi hatası ile dokümanın hatası arasında ayrım yapamamasıdır. Doküman bir yetke gibi okunur; onunla çelişen bir sonuç alan okurun ilk varsayımı kendi yanlışıdır. Kimi tekrar dener, kimi vazgeçer, kimi kendi yolunu bulur ve yalnız bir bölümü "burada yazan yanlış" der. Ölçüm bu payı üçte bir alır. #### Destek Talebinden Doküman Eksiğine Bildirim bir doküman eksiği olarak değil, bir çalışmama olarak gelir. Onu doküman kaydına çevirmek üç soruyla yapılır: okur **hangi cümleye** dayanarak davrandı, o cümle **hangi yüzeye** bağlı ve yüzey **ne zaman** değişti. ```text # ornek destek talebi ve dokuman kaydi , calistirilmamistir talep: "ölçüm gönderiyorum, kayıt kimliği yerine hata dönüyor" dayandığı cümle : referans / olcum_gonder — kaynak alanı zorunludur bağlı yüzey : imza değişim sürümü : 2 kayıt : bayat iddia, sessiz; aynı yüzeye bağlı 21 iddia daha var ``` Son satır bu işin asıl kazancıdır. Bir bildirim tek bir cümleyi düzeltmek için değil, **aynı yüzeye bağlı öbür iddiaları aramak** için kullanılır. Okur bir iddia bildirmiştir; bildirdiği şey aslında bir yüzeyin değiştiğidir ve o yüzeye yirmi iki iddia bağlıdır. Tek bildirim, hedefi belli bir doküman denetimini tetikler. #### Ölçümün Varsayımları - **DI31** — Elli altı iddia, dört tür ve dört yüzey ortak kurgudan alınır; ölçüm on ikinci sürümde yapılır ve o sürümde iddiaların hepsi bayattır. Ses çıkaran **17**, sessiz **39**. - **DI32** — Her okur ziyareti bir iddiaya düşer ve iddialar eşit olasılıkla seçilir. Gerçek bir kurulumda ilgi dağılımı eşit değildir; eşit dağılım kapsamanın **iyimser** kestirimidir. - **DI33** — Gömülü bayat iddiaya çarpan okur bunu her zaman bildirir; örnek çalışmamıştır ve arıza tartışılmaz. - **DI34** — Sessiz bayat iddiaya çarpan okurların **üçte biri** bildirir; kalanı kendi hatası sayar, vazgeçer ya da kendi yolunu bulur. - **DI35** — Aynı iddia birden çok kez bildirilse de bir kez sayılır; ölçülen şey ziyaret değil, **açığa çıkan iddia** sayısıdır. - **DI36** — Bildirim yalnız açığa çıkarır; düzeltmeyi ölçüm saymaz. Doküman ziyaretler boyunca değişmez ve yeni bayatlama eklenmez. - **DI37** — Rastgelelik ortak kurgunun üretecinden gelir ve tek modülle çağrılır; kümenin çözünürlüğü otuz dokuz sessiz iddiada **1/39**'dur. #### Ölçüm ```python """Geri bildirim dongusu: sessiz bayatlamanin okur uzerinden gorunur olmasi. Bolum 1 - artan okur ziyaretiyle bildirilen sessiz iddia sayisi. Bolum 2 - iki yuz kirk ziyaretten sonra tur basina kalan sessiz bayat. """ TOHUM = 20260816 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} SURUM = 12 ZIYARET = (30, 60, 120, 240, 480, 960) BILDIRIM_PAYI = 3 # sessiz bayata carpan okurun bildirme payi: ucte bir def uretec(tohum): d = tohum % 2147483646 + 1 def r(n): nonlocal d d = (d * 48271) % 2147483647 return d % n return r 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 bayat_mi(iddia, surum): return surum // SIKLIK[iddia["yuzey"]] >= 1 def dongu(liste, ziyaret_sayisi): """Her ziyaret bir iddiaya duser. Gomulu bayat ornek calistirilinca gorunur; sessiz bayat ancak okur bildirdiginde gorunur.""" r = uretec(TOHUM) carpan, bildirilen = set(), set() for _ in range(ziyaret_sayisi): iddia = liste[r(len(liste))] if not bayat_mi(iddia, SURUM): continue carpan.add(iddia["no"]) if iddia["gomulu"] or r(BILDIRIM_PAYI) == 0: bildirilen.add(iddia["no"]) return carpan, bildirilen L = iddialar() BAYAT = [i for i in L if bayat_mi(i, SURUM)] SESSIZ = [i for i in BAYAT if not i["gomulu"]] print(f"{SURUM}. sürümde iddia {len(L)}, bayat {len(BAYAT)}, ses çıkaran " f"{len(BAYAT) - len(SESSIZ)}, sessiz {len(SESSIZ)} " f"({len(SESSIZ) / len(BAYAT):.4f})") print() print(f"{'ziyaret':>8s} {'çarpılan':>9s} {'bildirilen sessiz':>18s} " f"{'kapsama':>8s} {'bildirim başına ziyaret':>24s}") for z in ZIYARET: carpan, bildirilen = dongu(L, z) b = [i for i in SESSIZ if i["no"] in bildirilen] print(f"{z:8d} {len(carpan):9d} {len(b):18d} " f"{len(b) / len(SESSIZ):8.4f} {z / len(b):24.1f}") print() _, bildirilen = dongu(L, 240) print(f"{'tür':>15s} {'sessiz':>7s} {'240 ziyarette bildirilen':>25s} " f"{'kalan':>6s}") for tur in TURLER: grup = [i for i in SESSIZ if i["tur"] == tur] b = [i for i in grup if i["no"] in bildirilen] print(f"{tur:>15s} {len(grup):7d} {len(b):25d} {len(grup) - len(b):6d}") ``` ``` 12. sürümde iddia 56, bayat 56, ses çıkaran 17, sessiz 39 (0.6964) ziyaret çarpılan bildirilen sessiz kapsama bildirim başına ziyaret 30 20 6 0.1538 5.0 60 34 10 0.2564 6.0 120 47 19 0.4872 6.3 240 54 31 0.7949 7.7 480 56 36 0.9231 13.3 960 56 39 1.0000 24.6 tür sessiz 240 ziyarette bildirilen kalan öğretici 7 6 1 nasıl yapılır 5 3 2 açıklama 12 9 3 referans 15 13 2 ``` #### Döngü Çalışır, Yavaş Çalışır Son sütun kapanır: **kapsama 1,0000**. Yeterince okur geldiğinde sessiz bayatların hepsi açığa çıkar. Geri bildirim döngüsü, üçüncü iddianın gerçekten panzehiridir; doküman denetiminden bağımsız olarak, kimsenin takvimine bir şey koymadan çalışır. Bedeli sağdaki sütundadır. İlk otuz ziyaret **6** sessiz iddia açığa çıkarır: bildirim başına **5,0** ziyaret. İki yüz kırk ziyarette kapsama **0,7949**'a ulaşır ve bedel **7,7**'ye çıkar. Son üç iddia için dört yüz seksenden dokuz yüz altmışa geçmek gerekir ve bildirim başına ziyaret **24,6** olur. **Kapsama doyduğunda maliyet beş kat artar**, çünkü kalan iddialar az okunan ya da bildirilmesi düşük olasılıklı olanlardır. `çarpılan` sütunu bu farkı ayırır. Dört yüz sekseninci ziyarette elli altı iddianın hepsine çarpılmıştır; yani doküman baştan sona okunmuştur. Buna karşılık bildirilen sessiz sayısı **36**'dır. Aradaki üç iddia, çarpılmış ama bildirilmemiştir: okur onları okumuş, yanılmış ve söylememiştir. **Okunmak düzelmek değildir.** Alt tablo iki yüz kırk ziyaretin türlere göre dağılımını verir. Referansın on beş sessiz iddiasının **13**'ü, açıklamanın on ikisinin **9**'u bildirilmiştir. Kalan sekiz iddia dört türe dağılır ve hiçbir tür temizlenmemiştir. Bu, önceki dersin denetim tablosuyla doğrudan karşılaştırılabilir: aynı otuz dokuz iddiayı tam kapsamlı bir doküman denetimi **56** iddia okuyarak tek geçişte bulur; geri bildirim döngüsü **960** ziyaretle bulur ve o ziyaretlerin her biri yanlış bir cümle okumuş bir okurdur. Karşılaştırma iki yolun rollerini belirler. **Denetim ucuzdur ve başlatılması gerekir; döngü kendiliğinden çalışır ve bedelini okur öder.** İkisi birbirinin yerine geçmez: döngü olmadan denetim nereye bakacağını bilmez, denetim olmadan döngü ödediği bedeli düşüremez. #### Özet - Sessiz bayatlama kendini göstermez; görünür hâle gelmesinin tek doğal yolu ona çarpan okurun bunu bildirmesidir. - Okur bildirimi bir doküman eksiğine üç soruyla çevrilir: dayanılan cümle, bağlı olduğu yüzey, yüzeyin değiştiği sürüm. Bir bildirim aynı yüzeye bağlı öbür iddiaları da hedef hâline getirir. - Otuz dokuz sessiz iddianın **31**'i **240** ziyarette, **39**'u **960** ziyarette açığa çıkar; kapsama **1,0000**'a ulaşır ama bildirim başına bedel **5,0** ziyaretten **24,6** ziyarete yükselir. - Dört yüz seksen ziyarette elli altı iddianın hepsine çarpılmış olmasına karşın bildirilen sessiz sayısı **36**'dır; okunmuş olmak düzeltilmiş olmak değildir. - Doküman denetimi aynı otuz dokuzu **56** iddia okuyarak bulur; döngünün bedelini yanılan okur öder. İkisi birbirinin yerine geçmez. #### Kurs Kapanışı Kurs tek bir ölçü kurdu ve on beş derste onu taşıdı: bir dokümanın sayısı uzunluğu değil, **hâlâ doğru olan iddia sayısıdır** — ve bayatlayanların kaçının **sessiz** olduğudur. Her ders kendi ölçümünü çalıştırdı; aşağıdaki tablonun her satırı o dersin kendi çıktı bloğundan okunmuştur. | ders | ölçülen | doğru kalan ya da sessiz bayat | |---|---|---| | Teknik Yazarlığın Kapsamı | iddia, tür, yüzey ve gömülülük dağılımı | sürüm 0'da 56/56 doğru; gömülü 17, sessiz 39; imza değişimi 22 iddia düşürür, sessiz payı 0,7727 | | Öğretici, Nasıl Yapılır, Açıklama ve Referans | dört türün ikinci sürümdeki ömrü | açıklama 11/12 (0,9167), referans 2/15 (0,1333); ömür oranı 6,875 kat | | Depo Belgeleri | üç depo belgesinin yüzey dağılımı ve yarılanma sürümü | yarılanma 3 / 3 / 12; sürüm 12'de karar kaydı 0/10 ve 10 sessiz | | API Referansı | elle yazılan ile üretilen referansın karşılaştırması | sürüm 6'da elle 0/15, üretilen 13/15; kurtarılamayan 2 iddia ad yüzeyinde | | Sürüm Notları | not biçiminin tarihlenebilir kıldığı iddia sayısı | ham liste 17/56 ve sessizlerden 0/39; anlam listesi 56/56 ve 39/39 | | Sorun Giderme İçeriği | belirtiden başlayan metnin karşıladığı okur kararı | belirti–neden–çözüm 51/51 (1,0000); kapsanan iddia 17/56, erişilemeyen 39 | | Okur Tanımı | ön bilgi varsayımının okunabilir kıldığı iddia | sürüm 3'te doğru 18; okunabilir 3'ten 18'e çıkar, bayat 38 ve sessiz 24 değişmez | | Yapı ve Başlıklandırma | okurun sorusuna ulaşana kadar okuduğu birim | ortalama adım 26,38'den 7,00'a; sürüm 6'da iki düzeyli düzende 24 sessiz bayat başlık | | Stil Rehberi | ikili adlandırmanın ürettiği belirsizlik | serbest rejimde aranan adla bulunan 25/56; yeniden adlandırmada kaçan 31, sessizi 23 | | Örnek ve Kod Parçacıkları | gömülülük oranının sessizliğe etkisi | sürüm 12'de 0/56 doğru, sessiz 39 (0,6964); rejime göre 0,8571 ile 0,4464 arası | | Görsel Kullanımı | diyagramın bağlandığı yüzey ve sesi | doğru/bayat değişmez (0/56); sessiz 39'dan karma şemada 56'ya çıkar | | Kod ile Birlikte Doküman | dokümanın incelemeye girmesinin bayatlamaya etkisi | birlikte sürümleme 300/672 ve 39 sessiz; inceleme 43/672 ve 15 sessiz | | Doküman Üretim Yaklaşımları | üretimin kurtardığı ve kurtaramadığı yüzey | sürüm 12'de kaynaktan üretim 22/56 doğru; kalan 34 bayatın 22'si sessiz | | Bayatlama ve Doküman Denetimi | denetim kapsamının bulduğu sessiz bayat | sürüm 12'de 56/56 bayat ve 39 sessiz (0,6964); denetimsiz bulunan yalnız 17 | | Geri Bildirim Döngüsü | okur bildiriminin açığa çıkardığı sessiz iddia | 240 ziyarette 31/39 (0,7949), 960 ziyarette 39/39; bedel 5,0'dan 24,6'ya | Kursun kendi kuralına kendi uyması bir biçim şartı değildi. Her ölçüm çalıştırıldı, her çıktı bloğu koşumdan alındı; bu derslerin gömülü iddiaları da bayatladıklarında ses çıkaracaktır. Bu kurs **Yazılım Geliştirme Pratiği** müfredatının sonuncusudur. Beş kurs beş ayrı şeyi ölçtü ve hepsi aynı soruyu farklı bir nesneye sordu: yapılan iş geriye ne bırakıyor? | kurs | ölçü ekseni | |---|---| | Sürüm Kontrolüne Giriş | kaydın hangi bölgede durduğu ve oradan geri getirilebilirliği | | Dallanma ve İşbirliği | tarihçenin yanıtlayabildiği soru | | İleri Git | işlemin dokunduğu nesne sayısı | | Kod İnceleme ve Ekip Süreci | bakılan eksen ve okunan öbek | | Teknik Yazarlık ve Dokümantasyon | kaç iddia hâlâ doğru, kaçı sessizce bayat | Birinci satır kursun kendi derslerinden okunmuştur: çalışma dizini, hazırlık alanı ve nesne veritabanı ayrımı, kurtarılabilirliğin ölçütünün içeriğin nesne veritabanına yazılmış olması, sıfırlanan işlemelerin veritabanında kalması ve erişilemez nesnelerin silinmemesi — hepsi tek bir ekseni kurar. Beş kurs birlikte bir ekip disiplini kurdu: değişikliğin kaydedilmesi, birden çok kişi arasında tümleştirilmesi, tarihçenin yönetilmesi, başkası tarafından okunması ve anlatılması. Hepsinin ortak yanı, **dilden bağımsız** olmalarıdır; sayılan şey hiçbir zaman yazılan kodun kendisi değil, onun çevresindeki işti. Sıradaki müfredatlar bu çevreden merkeze döner ve dilin kendisini ölçer: bir dilin sunduğu yapılar, o yapıların zorunlu kıldığı kararlar ve kararların programa bıraktığı iz.