Kurs Orta

Teknik Yazarlık ve Dokümantasyon

Bu kursun sonunda

Doküman türlerini okur kitleye ve amaca göre ayırır
API referansı ve öğretici metni farklı yapılarla yazar
Dokümanı kod ile birlikte sürümleyip güncel tutar

Kursa başla

Doküman Türleri

Ürün, geliştirici ve destek içeriğinin ayrımı; öğretici, nasıl yapılır, açıklama ve referansın ayrı işlevleri; depo belgeleri; uç nokta ve hata belgeleme düzeni; sürüm notunun okura anlamı; ve belirti-neden-çözüm yapısı.

01 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.
02 Öğ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.
03 Depo Belgeleri Tanıtım dosyası, katkı rehberi ve mimari karar kaydı aynı sürümde başlar ve ayrı hızda çöker: üçü de ilk iddiasını ikinci sürümde kaybeder, ama ilk ikisi üçüncü sürümde yarılanırken karar kaydı on ikinci sürümde yarılanır ve on iki bayat iddiasının onunun onu sessizdir.
04 API Referansı Referansın 15 iddiasının 13'ü imzaya bağlıdır ve elle yazıldığında altıncı sürümde 0/15 kalır; kaynaktan üretildiğinde aynı sürümde 13/15 kalır, kurtarılamayan 2 iddia ad yüzeyindedir ve referans hiç örnek taşımadığı için bayatlayan iddialarının hepsi sessizdir.
05 Sürüm Notları Dört tür ürünü bugünkü hâliyle anlatır ve hiçbiri zamanı taşımaz; ham değişiklik listesi on ikinci sürümde 56 bayat iddianın 17'sini tarihlendirir ve sessiz olanların 0'ını, aynı dokuz girdiye yanlışlanan iddia yazıldığında 56'sının 56'sı ve sessiz 39'un 39'u tarihlenebilir olur.
06 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.

Yazım Disiplini

Ön bilgi varsayımlarının açık yazımı, taranabilir metin kurma, terim tutarlılığı ve ses birliği, çalışır ve doğrulanabilir örnekler, ve diyagramın metne hizmet etmesi.

01 Okur Tanımı Yazılmamış ön bilgi varsayımı iddiayı yanlış yapmaz, okunamaz yapar; üçüncü sürümde hâlâ doğru olan 18 iddianın yeni okur için okunabilir olanı okur tanımı yokken 3, tam yazılmışken 18'dir.
02 Yapı ve Başlıklandırma Başlık düzeni okurun sorusuyla yanıtı arasındaki mesafeyi ölçer; otuz altı ziyarette başlıksız metin ortalama 26,38 adım isterken tür başlıklı 7,29, iki düzeyli 7,00 ister ve iki düzeyli düzen bu kazanç için altıncı sürümde 24 sessiz bayat başlık taşır.
03 Stil Rehberi Stil rehberi bir dayatma listesi değil, her kuralın neyi ölçtüğünün yazıldığı bir belgedir; aynı kavram iki adla anıldığında okur 56 iddianın 25'ini bulabilir, 52'si belirsiz kalır ve yeniden adlandırma taramasının kaçırdığı 31 iddianın 23'ü sessizdir.
04 Örnek ve Kod Parçacıkları Çalıştırılabilir örneğe gömülü iddia bayatlayınca ses çıkarır, gömülü olmayan çıkarmaz; 56 iddianın 17'si gömülüdür ve on ikinci sürümde bayatlayan 56 iddianın 39'u sessizdir — 0,6964.
05 Görsel Kullanımı Diyagramın bayatlama hızını çizim biçimi değil bağlandığı yüzey belirler: arayüz şeması ikinci sürümde yanlışlaşır, kavram şeması on ikincide; diyagram çalıştırılamadığı için taşıdığı her bayat iddia sessizdir ve karma şema on ikinci sürümde 56 iddianın 56'sını sessizleştirir.

Doküman İşletimi

Dokümanı sürümleme ve inceleme sürecine dahil etme, kaynaktan referans üretme yaklaşımları, eskiyen içeriğin tespiti ve yaşam döngüsü, ve destek taleplerinden doküman eksiği çıkarma.

01 Kod ile Birlikte Doküman Dokümanı kodla aynı depoda sürümlemek on iki sürümlük bayat borcunu 300/672'de bırakır, incelemeye de sokmak 43/672'ye indirir; incelemenin görmediği iki yüzeyde 15 iddia sessizce bayat kalır.
02 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.
03 Bayatlama ve Doküman Denetimi On ikinci sürümde 56 iddianın 56'sı bayattır ve 39'u sessizdir; sessizlik oranı 0,6964'tür ve sessiz olanı bulmak, doküman denetiminin iddia başına ödediği okuma bedeliyle ölçülür.
04 Geri Bildirim Döngüsü Sessiz bayatlama ancak okur bildirdiğinde görünür: 240 ziyaret 39 sessiz iddianın 31'ini açığa çıkarır, 39'unun tamamı için 960 ziyaret gerekir ve bildirim başına bedel 5,0'dan 24,6 ziyarete yükselir.