--- title: 'Teknik Yazarlığın Kapsamı' source: 'https://academia.sh/tr/kurslar/teknik-yazarlik/teknik-yazarligin-kapsami' course: 'Teknik Yazarlık ve Dokümantasyon' language: tr updated: '2026-08-17T18:10:49+00:00' license: 'CC BY-SA 4.0' --- # Teknik Yazarlığın Kapsamı 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?