- Diátaxis, teknik dokümantasyon yazımına yönelik sistematik bir yaklaşım sunan bir kavramdır. Bu yaklaşım, dokümantasyon kullanıcılarının ihtiyaçlarını anlamaya yönelik sistematik bir yaklaşımdan yola çıkar ve içerik, yapı ve biçime dair bir yaklaşım önerir.
- Antik Yunancadan türeyen Diátaxis, dört açık ihtiyacı ve bunlara karşılık gelen doküman türlerini tanımlar: öğreticiler, nasıl yapılır kılavuzları, teknik referans, açıklama. Dokümantasyonun bu ihtiyaç yapısına göre organize edilmesini önerir.
- Diátaxis, dokümantasyonun içerik (ne yazılmalı), stil (nasıl yazılmalı), yapı (nasıl organize edilmeli) ile ilgili sorunlarını çözer.
- Yalnızca dokümantasyon kullanıcıları için değil, yazarlar ve bakımını yapanlar için de değerlidir. Hafiftir, anlaşılması kolaydır ve uygulanması basittir. Uygulama kısıtları dayatmaz; dokümantasyon kalitesini artıran etkin ilkeler sunar.
İçerik
-
Bu web sitesi, Diátaxis'i uygulamaya ve anlamaya yardımcı olan iki ana bölüme ayrılır.
- Buradan başlayın. Bu sayfalar, yaklaşımı anında ve somut biçimde anlamaya yardımcı olur.
- Diátaxis'i uygulama
- Öğreticiler
- Nasıl yapılır kılavuzları
- Referans
- Açıklama
- Pusula
- İş akışı
- Bu bölüm, Diátaxis'in teori ve ilkelerini daha derinlemesine inceler ve bunu destekleyen ihtiyaç anlayışını sunar.
- Diátaxis'i anlamak
- Temeller
- Harita
- Kalite
- Öğreticiler ve nasıl yapılır kılavuzları
- Referans ve açıklama
- Karmaşık hiyerarşiler
- Buradan başlayın. Bu sayfalar, yaklaşımı anında ve somut biçimde anlamaya yardımcı olur.
-
Diátaxis, pratikte kanıtlanmış bir ilkedir. Yüzlerce dokümantasyon projesinde başarıyla benimsenmiştir.
- Gatsby, açık kaynak dokümantasyonunu yeniden yapılandırırken Diátaxis çerçevesini ana kaynak olarak kullandı. Dört çeyrek, her doküman türü için kullanıcının hedeflerini önceliklendirmeye yardımcı olur.
- Cloudflare geliştirici dokümantasyonunu yeniden tasarlarken Diátaxis, bilgi mimarisinin kutup yıldızı oldu. Yeni içeriğin nereye yerleştirileceğine karar verirken çerçeveye başvurulması, dokümantasyonu hem okuyucular hem de katkıda bulunanlar için daha net hale getirdi.
1 yorum
Hacker News görüşleri
Bir kullanıcı, asıl önemli farkındalığın tüm bilgiyi tek seferde aktarmak gerekmediğini anlamak olduğunu belirtiyor. Farklı okurlar için bilgiyi çeşitli biçimlerde yazmanın yararlı olduğunu söylüyor
Sequin belgelerinde Diátaxis çerçevesini uyguladıktan sonra belge akışının iyileştiğini anlatıyor. Ancak Diátaxis’in kendi belgelerinin biraz anlaşılması zor ve gereğinden uzun olduğunu da ekliyor
Teknik dokümantasyon yazarları, Diátaxis’in DITA’ya benzediğini söylüyor. Ancak kullanıcı ihtiyaçlarını gözden kaçırabileceğini ve bilgi yeniden kullanımını sağlamak için içeriğin küçük parçalara ayrılması gerekebileceğini belirtiyorlar
SwiftUI uygulaması geliştiren bir kullanıcı, modern teknik dokümantasyonun yetersiz ele alındığını düşünüyor ve belgelerin hem bakım yapanları hem de kullanıcıları dikkate alması gerektiğini savunuyor
Diátaxis’in dokümantasyonu yapılandırmak için faydalı olduğu, ancak fazla katı uygulanırsa bir tuzağa dönüşebileceği belirtiliyor
Diátaxis’in asıl değerinin, dokümantasyon yazma biçimini sadeleştirmesinde yattığı açıklanıyor. Her kullanıcının ihtiyacına göre belge yazmanın önemli olduğu vurgulanıyor
divio’nun görselinin daha sezgisel olduğu, ancak Diátaxis’in daha kapsamlı dokümantasyon sunduğu söyleniyor
Diátaxis benimsendikten sonra teknik dokümantasyonun büyük ölçüde iyileştiği ve sayfa sahipliği ile düzenli gözden geçirmenin başarılı dokümantasyona katkı sağladığı anlatılıyor
Diátaxis çerçevesinin basit ve anlaşılması kolay bir yapı sunduğu için teknik dokümantasyon yazımında yararlı olduğu belirtiliyor
Bir kullanıcı, Logdy dokümantasyonunu Diátaxis ile yazdığını ve bu yaklaşımın yazılım ürünlerini belgelendirmede ne kadar yararlı olduğu konusunda görüş istediğini söylüyor. Ayrıca ürün kullanımını bir blog yazısıyla etkili biçimde aktardığını anlatıyor