--- title: 'Sorun Giderme İçeriği' source: 'https://academia.sh/tr/kurslar/teknik-yazarlik/sorun-giderme-icerigi' course: 'Teknik Yazarlık ve Dokümantasyon' language: tr updated: '2026-08-17T18:10:49+00:00' license: 'CC BY-SA 4.0' --- # Sorun Giderme İçeriği 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.