Teknik Yazarlığın Kapsamı

Ö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.

# 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

"""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?