--- title: 'Doküman Üretim Yaklaşımları' source: 'https://academia.sh/tr/kurslar/teknik-yazarlik/dokuman-uretim-araclari' course: 'Teknik Yazarlık ve Dokümantasyon' language: tr updated: '2026-08-17T18:10:49+00:00' license: 'CC BY-SA 4.0' --- # Doküman Üretim Yaklaşımları Ü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.