Diátaxis: teknik dokümantasyon yazımına sistematik bir yaklaşım

Diátaxis, teknik dokümantasyon yazımına sistematik bir yaklaşımdır. Yazarı Daniele Procida, onu dokümantasyon üzerine düşünmenin ve dokümantasyon yapmanın bir yolu olarak sunuyor: içerik, mimari ve biçime ilişkin yaklaşımlar, dokümantasyon kullanıcılarının gerçek ihtiyaçlarının incelenmesinden doğuyor.

Dört dokümantasyon türü

Temel fikir, dört farklı ihtiyaca yanıt veren dört ayrı dokümantasyon türü bulunduğudur: eğiticiler (tutorials), nasıl yapılır kılavuzları (how-to guides), başvuru dokümanları (reference) ve açıklamalar (explanation). Her birinin amacı farklıdır ve her biri farklı biçimde yazılmalıdır. Eğitici, öğrenciyi öğrenme deneyimi boyunca elinden tutan bir derstir; her zaman pratiktir, sürüş dersi gibi. Nasıl yapılır kılavuzu, hâlihazırda yetkin bir kullanıcının gerçek bir hedefe ulaşmasına ya da sorunu çözmesine yönelik pratik yönergeler sunar; çalışmayla ilgilidir, öğrenmeyle değil. Başvuru dokümanları, doğru iş yapmak için gereken teknik olguları içerir: deniz haritası gibi kesin, eksiksiz ve yorumsuz. Açıklamalar ise bağlam ve arka plan sağlar, parçaları birbirine bağlar ve “neden” sorusunu yanıtlar.

Harita ve pusula

Diátaxis bu dört türü kavramsal bir haritaya yerleştirir ve belirli bir içeriğin nereye ait olduğuna karar vermeye yardımcı olan bir pusula ekler. Eğiticiler ve nasıl yapılır kılavuzları kullanıcının yaptıklarıyla — eylemle; başvuru ve açıklamalar ise kullanıcının bildikleriyle — bilişle ilgilidir. Eğiticiler ve açıklamalar beceri kazanmaya, yani öğrenmeye hizmet eder; nasıl yapılır kılavuzları ve başvuru dokümanları ise becerinin uygulanmasına, yani çalışmaya. Projeye göre, bu sınırların ihlal edilmesi ya da bulanıklaştırılması dokümantasyondaki sayısız sorunun merkezinde yer alıyor.

Pratikte kanıtlanmış

Yaklaşım hafif, anlaşılması kolay ve uygulama kısıtı dayatmayan bir yöntem olarak tanımlanıyor; ilkeleri yüzlerce dokümantasyon projesinde başarıyla uygulanmış durumda. Vonage’tan Greg Frileux, Diátaxis sayesinde yüksek kaliteli bir iç dokümantasyon oluşturulduğunu söylüyor; Megan Sullivan, Gatsby projesinin açık kaynak dokümantasyonunu yeniden düzenlerken bu çerçeveye dayandığını ve dört bölgenin belge türlerini önceliklendirmeye yardımcı olduğunu aktarıyor; Adam Schwartz ise Cloudflare geliştirici dokümantasyonu yeniden tasarlanırken Diátaxis’in “bilgi mimarisinin kuzey yıldızı” hâline geldiğini belirtiyor.

Nasıl başlanır

Sitenin kendi tavsiyesi şu: uygulayarak başlayın — hem de ne kadar küçük olursa olsun bir şeye. Önerilen çalışma döngüsü şöyle: önünüzdeki dokümantasyona bakın, iyileştirilebilecek bir yön olup olmadığını sorun, hemen şimdi yapabileceğiniz tek bir şey seçin ve onu yapın; sonra tekrarlayın. Teoriye inanmak zorunda değilsiniz; yazar bunu tamamen pragmatik bir yaklaşım olarak sunuyor ve değerinin daha iyi dokümantasyon üretmeye yardımcı olmasında yattığını söylüyor.