Yazılım ve API dokümantasyonu yazmanın yöntemi

Yazılım dokümantasyonu neden ayrı bir beceridir?

Kodu yazan kişi ürünü zaten bilir; doküman ise ürünü bilmeyen birine yöneliktir. Bu yüzden iyi dokümantasyon, iyi kod yazmaktan farklı bir beceridir: okuyucunun neyi bilmediğini tahmin etmek, onun amacına göre bilgiyi sıralamak ve gereksiz ayrıntıyı ayıklamak gerekir. Dokümanı olmayan ya da güncelliğini yitirmiş bir API'yi kullanmak isteyen geliştirici, kaynak koduna ya da destek ekibine yönelir ve bu hem zaman hem güven kaybıdır.

Bu işi yapan kişi bazı ekiplerde teknik yazar, bazılarında API'yi geliştiren mühendisin kendisidir. Her durumda ortak olan, okuyucu odaklı düşünmedir. Yazılan şeyin türü de okuyucunun anına bağlıdır: yeni başlayan biri öğretici ister, bir hatayla uğraşan biri sorun giderme notu ister, entegrasyonu bitirmek isteyen biri kesin bir başvuru metni ister.

Hangi doküman türleri vardır ve her biri ne işe yarar?

Yazılım dokümanları tek bir kalıba sığmaz. Başlıca türler şunlardır:

• Başlangıç kılavuzu: Kurulumdan ilk çalışan sonuca kadar kısa ve çalıştırılabilir bir yol sunar.
• Öğretici: Bir amaca adım adım götürür, öğrenmeyi hedefler.
• Nasıl yapılır rehberi: Belirli bir işi yapmak isteyen deneyimli kullanıcıya doğrudan çözümü verir.
• Başvuru (referans): Her uç noktayı, parametreyi, yanıtı ve hatayı eksiksiz ve tutarlı biçimde listeler.
• Kavram açıklaması: Sistemin neden böyle çalıştığını, temel fikirleri ve kısıtları anlatır.
• Sürüm notları ve geçiş rehberi: Neyin değiştiğini ve mevcut kullanıcının ne yapması gerektiğini söyler.

Bu türleri karıştırmak en yaygın sorundur. Öğretici içine uzun bir parametre listesi koyarsanız yeni başlayan boğulur; referans içine hikâye anlatırsanız deneyimli kullanıcı aradığını bulamaz. Her sayfanın tek bir türde olması ve türün başlıktan anlaşılması, bilgi mimarisinin temel kuralıdır.

API referansı adım adım nasıl yazılır?

API referansı, dokümantasyonun en çok başvurulan kısmıdır ve belirli bir düzen ister. Her uç nokta için aynı alanlar aynı sırayla bulunmalıdır: ne işe yaradığı, istek biçimi ve yöntemi, yol ve sorgu parametreleri, istek gövdesi, kimlik doğrulama gereksinimi, başarılı yanıt, olası hata yanıtları ve bir örnek.

Yazım sırası genellikle şöyle ilerler:

• Önce uç noktanın amacını tek cümleyle yazın: ne yapar, kim kullanır.
• Her parametre için ad, veri türü, zorunlu olup olmadığı, kabul edilen değerler ve davranışı kısaca belirtin.
• Gerçekçi bir istek örneği ve ona karşılık gelen gerçek bir yanıt örneği ekleyin; örnek değerler anlamlı olsun.
• Hata durumlarını başarılı yanıt kadar ciddiye alın: hangi koşulda hangi hata döner, kullanıcı ne yapmalı.
• Kısıtları açıkça yazın: istek sınırları, sayfalama davranışı, yeniden deneme güvenliği.

Birçok ekip bu referansı elle yazmak yerine OpenAPI gibi bir sözleşme dosyasından üretir. Bu durumda yazarın işi, sözleşmedeki açıklama alanlarını anlamlı doldurmak ve üretilen çıktıyı kavram ve rehber sayfalarıyla tamamlamaktır.

Bilgi mimarisi: doküman bulunabilir olmalı

En iyi yazılmış paragraf bile bulunamıyorsa işe yaramaz. Bilgi mimarisi, dokümanın nasıl bölümlendiğini, adlandırıldığını ve birbirine bağlandığını belirler. Üst düzeyde okuyucunun yolculuğunu izleyen bir yapı kurulur: önce ürüne giriş ve hızlı başlangıç, ardından kavramlar ve rehberler, en sonda ayrıntılı referans.

Pratikte dikkat edilecekler şunlardır: başlıklar eylem ya da konu bildirmeli ve arama motorunda ya da sayfa içi aramada karşılık bulacak sözcükleri içermeli; terimler boyunca aynı adla kullanılmalı (aynı kavrama bir yerde "istemci", başka yerde "müşteri uygulaması" denmemeli); sayfalar arası bağlantılar okuyucuyu bir sonraki mantıklı adıma götürmeli. Bir terimler sözlüğü ve tutarlı bir yazım kılavuzu, ekip büyüdükçe bu düzeni korur.

Docs-as-code: dokümanı kod gibi yönetmek

Dokümantasyonun güncelliğini yitirmesinin başlıca nedeni, kodla ayrı yerlerde ve ayrı süreçlerle yönetilmesidir. Docs-as-code yaklaşımında doküman, düz metin biçiminde (çoğunlukla hafif işaretleme dilleriyle) kod deposunda tutulur; değişiklikler çekme isteği ile önerilir, gözden geçirilir ve sürüm kontrolüne girer.

Bu yaklaşımın somut kazançları vardır: bir özellik değiştiğinde ilgili doküman aynı çekme isteğinde güncellenebilir; geçmiş değişiklikler izlenir; otomatik denetimler devreye girer. Örneğin bir sürekli entegrasyon hattı bozuk bağlantıları, biçim hatalarını ya da yazım kuralı ihlallerini yakalayabilir; kod örnekleri derlenerek ya da çalıştırılarak doğrulanabilir. Böylece "dokümandaki örnek artık çalışmıyor" türü sessiz hatalar azalır. Bu düzen, yazarlık ile mühendislik arasındaki sınırı da yumuşatır; mühendis doküman yazabilir, yazar da depoya katkı verebilir.

Mimariyi ve kararları belgelemek

Dokümantasyon yalnızca dışarıya dönük API'den ibaret değildir. Ekibin kendi içinde de sistemin neden bu hâlde olduğunu anlatan belgelere ihtiyacı vardır. Mimari belgelemede sistemin bileşenlerini ve aralarındaki veri akışını gösteren bir genel bakış, ayrıntılı bölümler için ek diyagramlar ve önemli tasarım kararlarının kısa kayıtları yer alır.

Karar kayıtları özellikle değerlidir: hangi sorun vardı, hangi seçenekler düşünüldü, hangisi seçildi ve neden. Aylar sonra yeni katılan bir mühendis, kodun kendisinden "neden" sorusunun cevabını çıkaramaz; bu kayıt çıkarır. Diyagramların da metne dönüştürülebilir biçimde (diyagram kodu olarak) tutulması, onları sürüm kontrolüne ve gözden geçirmeye sokar ve eskimelerini yavaşlatır.

Sık yapılan hatalar ve nasıl önlenir?

Dokümantasyonun kalitesini en çok düşüren hatalar şunlardır:

• Kodu tekrar eden açıklama: "kullanıcı kimliğini döndürür" gibi alan adından zaten anlaşılan cümleler değer katmaz. Alanın ne zaman boş olabileceğini, hangi biçimi taşıdığını yazın.
• Çalışmayan örnek: Elle yazılmış ve hiç denenmemiş örnek güveni yıkar. Örnekleri çalıştırıp doğrulayın, mümkünse otomatik denetleyin.
• Okuyucuyu varsaymak: Kısaltmaları açmadan kullanmak ve ön koşulları atlamak yeni başlayanı kaybettirir.
• Hata durumlarını yazmamak: Kullanıcı en çok bir şey ters gittiğinde dokümana bakar.
• Güncelleme sahipsizliği: Her sayfanın sorumlusu ve bir gözden geçirme düzeni olmalıdır; sürüm çıkışı, doküman güncellemesi olmadan tamamlanmış sayılmamalıdır.
• Aşırı uzun sayfalar: Bir sayfa tek bir işi çözmeli; gerisi bağlantıyla verilmeli.

İyi bir kontrol yöntemi, dokümanı ürünü hiç görmemiş bir meslektaşa verip sadece onu izleyerek hızlı başlangıcı tamamlamasını istemektir. Takıldığı her nokta bir dokümantasyon boşluğudur.

Bu beceriyi Mindset programlarında nerede çalışırsınız?

Mindset kataloğundaki Yazılım Dokümantasyonu ve API Referansı Yazımı programının modülleri Doküman Türleri ve Bilgi Mimarisi, API Referansı Yazımı ve Mimari Belgeleme ve Docs-as-Code başlıklarını taşır; yukarıda anlatılan eksenlere doğrudan karşılık gelir.

Referansı sözleşmeden üretmeyi öğrenmek isteyenler için OpenAPI ile Sözleşme Öncelikli API Tasarımı programının Şema Modelleme ve Bileşen Tasarımı, Hata Sözleşmesi ve Güvenlik Tanımları gibi modülleri tamamlayıcıdır.