--- title: 'Öğretici, Nasıl Yapılır, Açıklama ve Referans' source: 'https://academia.sh/tr/kurslar/teknik-yazarlik/ogretici-nasil-yapilir-aciklama-ve-referans' course: 'Teknik Yazarlık ve Dokümantasyon' language: tr updated: '2026-08-17T18:10:49+00:00' license: 'CC BY-SA 4.0' --- # Öğretici, Nasıl Yapılır, Açıklama 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?