- Teknik dokümantasyonun kullanıcıların durumuna göre farklı roller üstlenmesi gerektiği varsayımından hareketle, Diátaxis içerik, yapı ve biçimi birlikte ele alan bir yaklaşımdır
- Kullanıcı ihtiyaçlarını 4 kategoriye ayırır ve bunları sırasıyla tutorials, how-to guides, technical reference, explanation belge türleriyle eşleştirir
- Sadece basit bir sınıflandırma tablosu değil; ne yazılacağını, nasıl yazılacağını ve nereye yerleştirileceğini ele alan bir dokümantasyon tasarım çerçevesine daha yakındır
- Yazarların ve bakımını yapanların da dokümantasyon kalitesini değerlendirmesini kolaylaştırır; hafif, sezgisel ve belirli bir uygulama biçimini zorunlu kılmaması önemli avantajlarıdır
- Vonage, Gatsby ve Cloudflare örneklerinde olduğu gibi, dokümanlarda gezinilebilirliği ve bilgi mimarisini iyileştirmek isteyen ekipler için pratik bir ölçüt olarak kullanılabilir
Diátaxis'in ayırdığı 4 belge türü
- Diátaxis, teknik dokümantasyon yazmak ve işletmek için bir düşünme biçimi ve uygulama yöntemidir
- Başlangıç noktası, dokümantasyon kullanıcısının ihtiyaçlarını anlamaktır; buradan içerik, mimari ve biçime ilişkin ilkeler türetilir
- Dokümantasyon ihtiyaçları ve biçimleri 4 başlıkta ayrılır
-
tutorials
-
how-to guides
-
technical reference
- explanation
- Dokümantasyonun kendisi de bu 4 ihtiyacın etrafında organize edilmelidir ve Diátaxis üç soruyu birlikte ele alır
- content: ne yazılmalı
- style: nasıl yazılmalı
- architecture: nasıl organize edilmeli
-
Yazarlar ve bakımcılar için uygulanabilirlik
- Diátaxis, yalnızca dokümantasyon kullanıcıları için değil, dokümantasyonu yazanlar ve bakımını yapanlar için de faydalı bir yaklaşımdır
- Hafif ve anlaşılması kolaydır
- Uygulaması sezgiseldir
- Uygulama kısıtlarını zorunlu kılmaz
- Bakımcıların kendi çalışmalarını değerlendirebilmesi için kalite ilkeleri sunar
- Bu ilkeler, yüzlerce dokümantasyon projesinde başarıyla benimsenmiş uygulamalar olarak derlenmiştir
Gerçek dokümantasyon projesi örnekleri
- Vonage'dan Greg Frileux, Diátaxis sayesinde kullanıcıların beğendiği ve katkı sağlayanların ekleme yapmayı sevdiği bir iç dokümantasyon seti oluşturabildiklerini söylüyor
- Gatsby, açık kaynak dokümantasyonunu yeniden yapılandırırken Diátaxis çerçevesini temel kaynaklardan biri olarak kullandı; 4 alanın, her belge türündeki kullanıcı hedeflerini önceliklendirmeye yardımcı olduğunu belirtti
- Cloudflare, Cloudflare developer docs yeniden tasarımında Diátaxis'i bilgi mimarisinin ölçütü olarak benimsedi ve yeni içeriğin nereye yerleştirilmesi gerektiğine karar verirken bu çerçeveye başvurdu
1 yorum
Hacker News yorumları
Profesyonel olarak yazı yazmayan biri olarak bile, ayrıntılardan bağımsız şekilde buradan çıkardığım en önemli ve temel içgörü şu oldu: her şeyi tam olarak bir kez söylemek zorunda değilsiniz.
Bu düşünceyle karşılaşmadan önce tek bir metin akışının “belgenin tamamı” işlevini görmesi gerektiğini sanıyor, kendi kendimi düğümlüyordum.
Farklı okurlar için aynı bilgiyi farklı şekillerde yazabileceğinizi fark etmek bile çok yardımcı oluyor.
Okur örnekler arasındaki ortak paydayı bulacağı için, tek bir örnekle açıklamaya kıyasla daha az muğlak olur.
İncil'deki Süleyman'ın Meselleri gibi metinlerin yazarları da bu tekniği çok kullanır.
Özette “Bu makale, Y'yi Z ile değerlendirerek X'in geçerli olduğunu gösterir” diye yazarsınız; girişte ise A sorununun B yüzünden önemli olduğunu ama X yönünün gözden kaçtığını, Y değerlendirildiğinde Z'den farklı olarak gerçekçi zorlukların ortaya çıktığını açıklarsınız ve tekrar “Özetle, X nedeniyle Y, Z'den daha iyidir” diye toparlarsınız.
İlgili çalışmalarda da Z'nin yaklaşımının neyi iyileştirdiğini, ancak ileride gösterileceği gibi yeterli olmadığını anlatmaya devam eder; her bölümde ana mesajın etrafında dönüp durarak onu yeniden ele alırsınız.
İki hafta önce bu framework'ü Sequin dokümantasyonuna uyguladım; sırf bir çerçeve olması bile çok iyi geldi.
Artık doküman akışı çok daha iyi ve neyi nereye koyacağımı bildiğim için doküman eklemek ve bakımını yapmak da kolaylaştı.
Ancak ironik biçimde Diátaxis dokümanlarının kendisi biraz zor ve laf kalabalığı içeriyor; birkaç kez okuduktan sonra kafama oturdu.
Ekibe anlatırken bunu düdüklü tencere gibi bir pişirme aracı satın almaya benzettim: önce hızlı başlangıçla (tutorial) A'dan B'ye kabaca nasıl gidileceğini görürsünüz; sonra sevdiğiniz belirli bir yemeğin nasıl yapılacağını aramak how-to'dur; aklınıza ayrıntılar takılırsa referans bölümünde fasulye türlerine göre kesin pişirme sürelerine bakarsınız; basıncın pişirme süresini neden değiştirdiğini ya da güvenlik mekanizmasının nasıl çalıştığını da öğrenmek istediğinizde açıklama materyallerini okursunuz.
Komik şekilde bizim dokümanlar tamamen ters durumdaydı ve “How Sequin Works” gibi bir açıklamayla başlıyordu.
Mühendislerin doğal dürtüsü, önce çalışma prensibini ve neden böyle yaptığımızı anlatarak zihinsel model kazandırmaktır; ama insanların buna ayıracak zamanı ve sabrı yok.
Hızlı başlangıç → how-to → referans akışıyla kullanıcıyı dünyaya alıştırmak, gerçekten ilgisini kazandıktan sonra da açıklama materyalleriyle yaklaşımı ikna etmek daha iyi.
https://sequinstream.com/docs
Dokümanlar çoğu zaman şirketin aracının sadece bir araç olduğunu kabul etmekten utanıyormuş gibi “yenilikçi sinerji deneyimi” türü saçmalıklarla muğlaklaşır ya da tam tersine “bu ürün neden var” konusuna gelmeden önce aşırı somut ayrıntılara iner.
Yalnız dokümanda CDC tekrar tekrar geçiyor ve tanımını aramam gerekti. Kariyerimde CDC'yi birkaç kez uygulamış olsam da kısaltmaya aşina değildim.
Akış nihayetinde okurun seçimidir; benim kafam önce genel açıklamayı, sonra how-to ve tutorial'ları arayacak şekilde çalışıyor.
Teknik dokümantasyon yazarı açısından Diátaxis, DITA'ya benziyor: https://www.oxygenxml.com/dita/1.3/specs/archSpec/base/information-typing.html
Ancak bu tür sistemler, kullanıcının gerçekte ihtiyaç duyduğu şeyi kaçırabilir.
Teknik dokümantasyon yalnızca doküman platformu içinde kullanılacaksa Diátaxis uzun süre iyi uyabilir; fakat aynı bilgi UI, doküman portalı, mobil uygulama gibi birden fazla yerde kullanılabiliyor ve kullanılmalıysa, bilgiyi daha küçük parçalara bölüp farklı şekillerde bir araya getirmeniz gerekebilir.
Buna içerik yeniden kullanımı denir; aynı içeriğin birden fazla konumda kullanılmasıdır.
İçerik yeniden kullanımı için bilgi yazma ve düzenleme yaklaşımlarından biri “every page is page one” kavramında açıklanıyor: https://everypageispageone.com/the-book/
Kaynak ve zaman varsa proje başlangıcında UX araştırması öneririm. Böylece ileride aşırı kısıtlayıcı bir bilgi modeli yüzünden boğulma durumundan kaçınabilirsiniz.
Nielsen/Norman da bu alanı çok araştırdı ve ilgili sorunların çözümü için ilginç öneriler sunuyor: https://www.nngroup.com/articles/information-foraging/#toc-what-is-information-foraging-2
DITA görev, referans, kavram gibi konu türlerini ayırır; ancak tutorial'lar veya çözüm kılavuzları bu konu türlerinin bir kombinasyonu olur.
Burada tekil konulardan daha büyük çıktılara odaklanılıyor gibi.
DITA'nın içine çok derin girmiş olduğun için karmaşıklığın sorun olup olmadığını da merak ediyorum.
İçeriği yeniden kullanılabilir parçalara bölüp DITA veya DocBook semantiğiyle işaretlemek, büyük dil modellerinin bunu “anlamasını” çok daha kolaylaştıracak gibi geliyor; ama buna dair veri görmedim.
Günümüzde doküman yazmanın, XSL/FO ve akrabalarıyla boğuşmaktan daha iyi yolları var.
Teknik dokümantasyon tarafında zaten çok popüler ve neredeyse standart sayılır.
Ancak bazen bu yaklaşım fazla ileri götürülüp dokümantasyon sayfalarında kelimenin tam anlamıyla yalnızca bu dört kategori bırakılıyor; bu da genellikle pek iyi çalışmıyor.
Asıl olarak yazarın “bu bir rehber, o yüzden öğretmeye çalışma; sonuca ulaşmaya odaklan” gibi bir düşünceyi korumasına yardımcı oluyor.
Gerçekte ise bu kadar katı sınırlar pek istenen bir şey değil; bir rehberin içinde biraz tutorial olması da sorun değil.
Bu yaklaşımın gerçekten tıkandığı yerin, kadranlar arasındaki bağlantılar eksik olduğunda ortaya çıktığını düşünüyorum.
Örneğin bir yazılım framework’ünde rehber, eninde sonunda kullanılması gereken belirli sınıf veya metotların referans dokümanlarına link vermiyorsa, çevredeki bağlamı keşfetmek çok daha zorlaşıyor.
Bazı somut framework dokümanları kadranları bu şekilde ayırdı ve bu dokümanlarla ilgili en büyük can sıkıntılarından biri de tam olarak bu.
Ortada başka uzman yoksa, yeni başlayan biri için “kendi başına doğru olanı yapmaya çalışmak” yerine kurallara sıkı sıkıya uymak daha iyi olabilir.
Yeni başlayan kişi tanımı gereği bu yargıyı verecek uzmanlığa sahip değildir; deneyim kazandıkça belirlenmiş kurallardan nerede sapılması gerektiğini görmeye başlar.
Bu, bir yemek kitabına bakarak ev yemeği yapmak ile profesyonel bir şefin sezgi ve tada göre malzemeleri tencereye atması arasındaki farka benzer.
Ancak tutorial içinde tek bir açıklama cümlesi bile olmaması gerektiğini savunup kuralların harfi harfine uygulanması gerektiğini söyleyen biriyle çalışmıştım.
Bu tür sistemlerin tehlikesi de tam olarak burada.
Bu, “global değişkenleri değiştirme” veya “fonksiyonları kısa yaz” gibi programlama ilkelerine benziyor.
Kusursuz şekilde uymak gerekmiyor, ama çoğu durumda ters yönden ziyade bu yöne doğru ilerlemek daha iyi.
Bu yüzden üstteki bölümü Claude’dan Diátaxis’e göre sınıflandırmasını istedim; ağırlıklı olarak açıklama olduğunu, içine bazı referans dokümanı öğelerinin karıştığını ve Diátaxis açısından ideal olmadığını söyledi.
Hiperparametre ayarlamanın kavramını ve önemini saf şekilde açıklayan bir bölüm ile mevcut araçları ve yöntemleri listeleyen ayrı bir referans bölümü olarak ayrılmasının daha iyi olacağını söyledi.
Ancak ardından bu bütünleşik yaklaşımın kullanıcı rehberi bağlamında neden iyi çalıştığını da özetledi: İnsanların gerçekten öğrenme akışını izliyor, kavramlarla uygulamayı hemen birbirine bağlıyor, temel kavramlardan karmaşık araçlara doğru aşamalı olarak açılıyor ve teori ile pratiği birleştirerek pratik değer sağlıyor.
İlk SwiftUI uygulamamı yayımlamayı yeni bitirmiş biri olarak, modern teknoloji sektöründe dokümantasyonun fazlasıyla özensiz ele alındığını güçlü biçimde hissediyorum.
Apple’ın işten çıkardığı mükemmel teknik yazarların çalışmalarını çok özlüyorum; Apple mühendisleri doküman yazma konusunda gerçekten kötü.
Bununla birlikte “dogmatik” yaklaşımlara karşı her zaman temkinliyim. Gerçeklik gerektirse bile esnemeyen bir “rahip sınıfı”nın ortaya çıkması çok kolay.
Bu doktrini ilk ortaya koyan kişiler onu harika şekilde kullanıyor, ama ardından gelen “rahipler” işi bozup yaklaşımı bir lanete dönüştürebiliyor.
Pek çok iyi fikir, aşırı katı uygulama yüzünden mahvoldu. “Agile”ın ne hale geldiğine bakmak yeterli.
Dokümanın temelde iki yüzü var: bakım yapanlar ve kullanıcılar. İkisinin ihtiyaçları çok farklı olduğu için muhtemelen tamamen farklı ekipler tarafından ele alınmaları gerekiyor.
Dokümanın farklı yerlerdeki kopyalarının senkronizasyondan kopması gibi bir sorun da var, ama önemli olan sonuç.
Birden fazla örneği etkili biçimde senkronize edebiliyorsanız doküman tüketici için etkili ve yararlı olur.
Kusursuz biçimde formatlanmış ve senkronize edilmiş bir doküman bile kimse okumuyorsa değersizdir.
SNL’de Phil Hartman’ın canlandırdığı The Anal-Retentive Chef, hazırlığa o kadar çok zaman ayırıyordu ki gerçek yemek gösterimini yapamıyordu; teknoloji alanında da buna çok rastlıyorum.
Toolchain ve kütüphaneler kusursuz olabiliyor, ama gerçekte kullanılamayabiliyor.
Dokümantasyon; insan doğası ve psikoloji, grafik tasarım, bilgi mimarisi, teknik altyapı, yayıncılık ve dağıtım gibi birçok alanın karışımıdır.
Çoğu projede dokümantasyon sonradan yapılacak bir iş gibi görülüyor, ama bence gereksinim aşamasından itibaren birinci sınıf bir konu olmalı.
Doküman yapısını ne kadar derine kadar inceleyeceğinizin sonu yok, ama sızıntı yapan noktaları bulana kadar harika bir destek tekerleği görevi görüyor.
Bu, iyi bir fikrin yaygın yanlış anlaşılmasının veya hatalı uygulanmasının fikrin kendisini bozduğu anlamına geliyormuş gibi geliyor.
Aksine, gerçek uygulamadan kazanılacak deneyim vardır. İlk fikir aslında iyi değilse bu bir yanılsamayı yıkar; kötü örnekler ise yanlış yorumlandığında başarısızlığa yol açan belirsizlikleri ortaya çıkarıp fikri daha rafine hale getirir.
Ancak kötü uygulamalara alışan insan sayısı artarsa fikrin popülerliği azalabilir ve rafine uygulamalara olan talep de düşebilir.
Bu, fikrin kendi yozlaşmasından ziyade anti-commons trajedisine daha yakındır.
Diátaxis dokümanları yapılandırmak için harika, ama asıl değeri doküman yazma biçimini basitleştirmesinde.
Her şeyi tek bir “mükemmel dokümana” tıkıştırma fikrinden uzaklaştırıp, farklı kullanıcıların farklı ihtiyaçları olduğunu fark ettiriyor.
Tutorial, takip ederek öğrenmek içindir; rehber belirli bir sorunu çözmek içindir; referans dokümanı hızlı başvuru içindir; açıklama ise “neden” sorusunun derinine iner.
Sırf bu netlik bile daha kullanışlı dokümanlar yazmanızı sağlayabilir.
Ancak her sistemde olduğu gibi, buna da fazla sıkı sarılırsanız tuzağa dönüşür.
Yoksa birleşik bir paradigma mı var, merak ediyorum.
Bizim organizasyonda bu yöntemi kullanıyoruz ve benimsediğimizden beri teknik dokümanlar tamamen başka bir seviyeye çıktı.
Buna sayfa sahipliği ve her sayfa sahibinin periyodik incelemesi de eklenince, gördüğüm tek başarılı teknik dokümantasyon çalışması oldu.
Divio’nun kullandığı görselin çok daha sezgisel olduğunu düşünüyorum: https://docs.divio.com/documentation-system/
Ancak Diátaxis tarafı her bir anlamı daha kapsamlı biçimde belgelemiş gibi görünüyor
Diataxis.fr’deki Divio yeniden yazımı, grafik olarak daha az dağınık ama özünde Divio’da kullanılanla aynı olduğunu düşünüyorum
İki kaynağı da, kendi web siteleri bağlamında sundukları fikirler açısından fiilen aynı belge olarak gördüm
Hangi yönünün daha sezgisel olduğunu bilmek isterim
Bu fikri seviyorum ve fikri geliştiren kişiyle PyConUK’ta birkaç kez karşılaşma şansım oldu. Yetenekli ve çok nazik biri
Ancak dokümantasyonun farklı alanlarını bu kadar katı biçimde ayırma konusunda çekinceliyim
Bir sprint’te hazırladığım dokümanın birden fazla biçimi karıştırdığı için kabul edilemez olduğu söylenmişti. Bu arada bunu söyleyen Daniele değildi
Otoriteye başvurmak istemem ama 20 yılı aşkın süredir öğretmenlik yaptım; insanların bir işi yaparken aynı anda anlayış da geliştirebilmesi için nasıl açıklama yapılacağı ve öğrenmenin nasıl yapı iskelesiyle destekleneceği konusunda kendimce bir sezgim var
Tam bir katılık olmadığı sürece, bu dokümantasyonun nasıl oluşturulacağını ve her belge türünün ne yapması gerektiğini belirlemek için harika bir araç
Örneğin numpy’deki doküman örneklerinde, “gökten düşmüş sihir” gibi örnekler yerine çok daha iyi seçilebilecek örneklere sıkça rastlıyorum
İyi seçilmiş tek bir örnek, kullanımı gösterirken köşe durumları veya dikkat edilmesi gereken noktalar hakkında da çok şey öğretebilir
Teoride doğru olduğunu düşünüyorum ama katılmakta zorlanıyorum. Kelimeler birbirine çok yakın
Bana göre “tutorial”, “how-to guide” ve “explanation” pratikte neredeyse eş anlamlı gibi geliyor
Derinlemesine düşününce her kategorinin haklı bir gerekçesi olduğunu anlıyorum ama anlamsal olarak çok yakın oldukları için zihnim farkı göremiyor
Bir şeyin nasıl çalıştığını öğrenmek istediğimde “tutorial” ve “how-to guide” görürsem hangisine tıklamam gerektiğini bilemiyorum ve sadece ilkine tıklıyorum
Size daha iyi uyan terimleri bulmaya çalışmak da faydalı bir alıştırma olabilir
Ya da bunu eylem/biliş, yani “yapmak vs düşünmek” ve edinim/uygulama, yani “öğrenme sırasında vs iş sırasında” ayrımı üzerinden anlayabilirsiniz
Tutorial ile how-to guide’ı ayıran özel bir sayfa da var: https://diataxis.fr/tutorials-how-to/
En basit ayrımlardan biri, tutorial’ın Stack Overflow’da yapılamayan şey olmasıdır
Tutorial, öğretmenin belirlediği ders planını takip eder ve öğrencinin bilmediğini bile bilmediği boşlukları dolduran bir süreçtir
Stack Overflow’da soru sormanız gerekir, ama tutorial henüz ne soracağını bile bilmeyen kişiler içindir
Basit bir işin nasıl yapılacağına dair popüler sorular da çoktur, ama o biçime uyması için belirsizce yardım istemek değil, soru sormak gerekir: https://meta.stackoverflow.com/questions/284236
Diátaxis dokümanı farkı oldukça verimli biçimde açıklıyor: tutorial öğrenme odaklı deneyimdir, how-to guide hedef odaklı talimattır, reference bilgi odaklı teknik açıklamadır, explanation ise anlama odaklı tartışmadır
Bu sistemdeki “tutorial”ı gündelik bir kelime olarak değil, teknik terim olarak okumak yeterli
Bir psikoloğun söylediği “depression”ın gündelik anlamıyla tam olarak aynı olmamasına benzer
Yine de Type I-IV tutorial demekten daha iyi
Ders anlatımı explanation’dır; tutorial veya uygulamalı alıştırma ise yönlendirilmiş deneyimdir ve Microsoft’un sahte şirketi Contoso’yu akla getirir
How-to guide, bir çözümü ararken ya da ChatGPT’ye sorarken ihtiyaç duyduğunuz şeydir; reference ise eş anlamlılar sözlüğü, ansiklopedi, kullanım kılavuzu gibi bir şeydir
Video oyunlarında yerleşik tutorial olur, ama zor bulmacalar için hâlâ walkthrough gerekir; tuş ayarları ise reference’tan kontrol edilir