Teknik dokümantasyon, kod derlendikten sonra bitirilen yan bir görev değildir. Her yazılım projesinin merkezinde yer alır; yeni bir geliştiricinin ilk gününde bir hatayı düzeltip düzeltemeyeceğini veya bir kullanıcının beş dakikalık kafa karışıklığından sonra ürününüzü terk edip etmeyeceğini belirler. İyi dokümanlar, kullanıcıların gerçek görevleri yerine getirmesine yardımcı olur. Gelecekteki bakımcıların bir modülün neden var olduğunu ve her şeyi bozmadan nasıl değiştirebileceğini anlamalarına yardımcı olur. Yine de çok fazla ekip, dokümantasyonu sonradan akla gelen bir şey, aceleyle hazırlanmış bir README veya çürümeye bırakılmış bir wiki sayfası olarak görür. Gerçekten yararlı dokümantasyon yazmak, bilinçli olarak geliştirebileceğiniz bir beceridir.
Yazmadan Önce Okuyucularınızı Tanıyın
Tek bir başlık yazmadan önce, kimin okuduğuna karar verin. Bağlantı havuzu (connection pool) ayarlarını arayan bir veritabanı yöneticisi ile React bileşen özellikleri (props) arayan bir front-end geliştiricinin ortak hiçbir noktası yoktur. Son kullanıcılar mimari diyagramlara değil, numaralandırılmış adımlara ve ekran görüntülerine ihtiyaç duyar. Nasıl PDF dışa aktaracaklarını bilmek isterler, render hattının (rendering pipeline) nasıl çalıştığını değil. Kütüphanenizi entegre eden geliştiricilerin kesin fonksiyon imzalarına, hata kodlarına ve kopyalayıp yapıştırılabilir kod parçacıklarına (snippets) ihtiyacı vardır. Sistem yöneticilerinin ise kurulum ön koşullarına, ortam değişkenlerine (environment variables) ve en yaygın hata modlarından başlayan sorun giderme akışlarına ihtiyacı vardır.
Eğer üç gruba da tek bir metin yığınıyla hizmet vermeye çalışırsanız, herkes kaybeder. Ayrı yollar oluşturun. Tek bir sayfa bile "Operatörler için" ve "İstemci geliştiricileri için" gibi net başlıklarla düzgün bir şekilde bölümlere ayrılabilir. Amaç, "Bu paragraf benim için mi?" sorusunun yarattığı zihinsel sürtünmeyi ortadan kaldırmaktır.
Gürültüyü Azaltın
Netlik, zekice olmaktan daha üstündür. Kısa cümleler kullanın. Etken çatı (active voice) kullanın. "Veritabanını başlatın" ifadesi, "Veritabanı kullanıcı tarafından başlatılmalıdır" ifadesinden daha nettir. "Idempotency" veya "serialization" gibi teknik bir terim kullanmanız gerektiğinde, bunu satır içinde tanımlayın veya bir sözlüğe (glossary) bağlantı verin. Ön bilgi varsaymayın.
Pratik bir test: Paragrafınızı yüksek sesle okumayı deneyin. Eğer nefesiniz yetmiyorsa, cümle çok uzundur. Başka bir test: Süslü fiillerin yerine basit olanları koyun. Eğer "utilize the API" gibi bir ifade anlam kaybı olmadan "use the API" haline gelebiliyorsa, değişikliği yapın. Sade dil, basitleştirilmiş bir dil demek değildir. Kurumsal dolgu malzemelerinden arındırılmış, kesin bir dil demektir.
Gerçekten Yardımcı Olan Yapı
Düzensiz bir kılavuz, hiç kılavuz olmamasından daha fazla zaman kaybettirir. Dokümantasyonunuzu bir huni gibi düşünün. En üste, projenin ne yaptığını ve kimin ilgilenmesi gerektiğini açıklayan kısa bir genel bakış yerleştirin. Ardından, okuyucunun yerel kurulumu hakkında hiçbir varsayımda bulunmayan kurulum talimatlarını ekleyin. Sonra, baştan sona tamamlanmış, gerçekçi senaryolar üzerinden ilerleyen eğitimler (tutorials) ekleyin. API referansları sonra gelir. Bunlar kapsamlı ancak taranabilir olmalı; alfabetik sırayla dökülmek yerine kaynak veya fonksiyona göre gruplandırılmalıdır. Son olarak, belirli semptomları ele alan sorun giderme kılavuzlarını yerleştirin. "Connection refused" hatası alan bir kullanıcının, "Permission denied" hatası alan birinden farklı bir cevaba ihtiyacı vardır. Hataları soyut kategorilere göre değil, mesajlara veya bağlama göre gruplandırın.
Listeler ve kod blokları yoğun metni böler ve okuyucuların ihtiyaç duydukları tam komutu taramalarına olanak tanır. İyi yerleştirilmiş bir madde işaretli liste, kafa karıştırıcı bir paragrafı bir eylem dizisine dönüştürebilir.
Sadece Anlatmayın, Gösterin
Soyut açıklamalar kullanıcıları hayal kırıklığına uğratır. Bir aracın nasıl yapılandırılacağını tarif ediyorsanız, dosyanın tam içeriğini gösterin. Kurulum, başlatma ve yaygın yapılandırmalar için kod parçacıkları sağlayın. Örnek girdileri ve beklenen çıktıları yan yana gösterin. API'niz JSON döndürüyorsa, JSON'u gösterin. Bir CLI aracı tablo çıktısı üretiyorsa, tabloyu gösterin. Bir iş akışının açıklamasının bir gösterime eşdeğer olduğuna asla güvenmeyin.
En önemlisi, yayınlamadan önce her örneği temiz bir ortamda test edin. Kendi kod parçacığınızı yeni bir konteyner veya sanal makineye kopyalayın. Eğer bir bağımlılığı (dependency) belirtmeyi unuttuğunuz için hata veriyorsa, kendinizi bir dizi sorundan kurtarmışsınız demektir. Somut örnekler, teknik yazımda yatırım getirisinin en yüksek olduğu noktadır; çünkü belirsizliği eyleme dönüştürürler.
Canlı Tutun
Dokümantasyon, koddan daha hızlı bozulur. Bir metod imzası değişir, varsayılan bir port taşınır, bir bağımlılık değiştirilir ve aniden talimatlarınız bir çıkmaza girer.