Bir ürün dokümantasyonu hazırlamak, bir blog yazmaktan farklı bir zihinsel model gerektirir. Blogda her yazı bağımsız bir birim olarak var olabilir; yazar kendi iç mantığıyla ilerler. Dokümantasyonda ise her sayfa bir zincirin halkasıdır. Kullanıcı o sayfaya nereden geldiğini bilmek ister, nereye gideceğini görmek ister ve hangi bilginin tam olarak "şu an için gerekli" olduğunu anlamak ister. Yapı kurulmadan içerik üretilirse, zamanla okunması güç, gezinmesi yorucu bir yığın ortaya çıkar.

Dokümantasyon siteleri bu yüzden ayrı bir tasarım sorunudur. Çoğu ekip bunu geç fark eder: içerik belirli bir hacme ulaştığında, navigasyon taşmaya başladığında veya yeni kullanıcılar "başlangıç için ne okumam lazım?" diye sorar hale geldiğinde. O noktada yapıyı düzeltmek, baştan kurmaktan çok daha maliyetlidir; çünkü içerik zaten mevcut URL'lere yayılmıştır, yazar alışkanlıkları yerleşmiştir ve yönlendirme zinciri giderek karmaşıklaşmıştır.

Aynı belgeyi okuyan üç farklı kullanıcı düşünün: biri ürünü ilk kez kuran bir geliştirici, biri belirli bir API uç noktasını araştıran deneyimli kullanıcı, biri de satın alma kararı öncesinde teknik derinliği ölçen bir yönetici. Bu üçünün navigasyon ihtiyacı birbirinden tamamen farklıdır. Dokümantasyon yapısı bu farklılığı karşılayacak biçimde kurgulanmadığında, her grup aradığını bulmakta zorlanır.

Bu yazı, bir dokümantasyon sitesinin nasıl yapılandırılması gerektiğini mimari açıdan ele alır. Navigasyon mantığından URL kurgusuna, içerik modelinden sürüm yönetimine kadar temel yapısal kararlar ve bunların pratikte nasıl şekillendiği inceleniyor.

Dokümantasyon sitesi diğer içerik sitelerinden farklı bir mantıkla kurulur

Blog veya haber sitelerinde içerik kronolojiktir ya da konu başlıklarına göre ayrışır. Kullanıcı genellikle birbirinden bağımsız parçalar okur ve aralarındaki sıra kritik değildir. Dokümantasyonda ise içerik doğrusal olmak zorunda değildir, ama kullanıcının giriş noktasına göre farklı yollar sunabilmesi gerekir. Bu temel ayrım, yapıyı baştan farklı biçimde kurmayı zorunlu kılar.

Bir blog kategorisi altında 50 yazı bulunabilir; bunlar arasındaki sıra önemsizdir. Bir dokümantasyon bölümü altındaki 10 sayfa ise belirli bir öğrenme veya görev sırasına karşılık gelir. "Kurulum" bölümü "Yapılandırma"dan önce gelir, çünkü biri diğerinin önkoşuludur. Bu önkoşul ilişkileri navigasyonda görünür kılınmadığında, yeni kullanıcılar sırayı tahmin etmek zorunda kalır ve çoğunlukla yanlış tahminde bulunur.

Dokümantasyon sitesinin diğer içerik sitelerinden ayrıştığı bir başka nokta güncelleme sıklığı ve kapsamıdır. Blog yazısı bir kez yayınlanır, nadiren değişir. Dokümantasyon sürekli güncellenir; bazen bir ürün sürümüyle birlikte tüm bölüm yeniden yazılır. Bazen yalnızca bir parametre adı değişir ama bu değişiklik ona bağlı on sayfayı etkiler. Bu dinamik yapı, dosya organizasyonu ve URL kurgusu açısından önceden planlamayı zorunlu kılar; yoksa her güncelleme domino etkisi yaratır.

İçerik derinliği de farklıdır. Blog yazısında genellikle tek bir konu, tek bir bakış açısıyla ele alınır. Dokümantasyon ise aynı kavramı farklı soyutlama düzeylerinde sunmak zorunda kalabilir: hem "nedir?" sorusunu yanıtlayan bir kavramsal açıklama, hem adım adım uygulama kılavuzu, hem de tam teknik referans. Bu üç içerik tipini tek bir sayfada toplamak yerine üç ayrı sayfaya ayırmak, yapının sağlığını koruyan temel karardır.

Kullanıcı tipi, belgenin nerede duracağını belirler

Dokümantasyon tasarımının çıkış noktası "bu belgeyi kim okuyacak?" sorusudur. Kullanıcı tipi, içeriğin hem nerede yer alacağını hem de nasıl yapılandırılacağını belirler. Farklı kullanıcı tiplerini aynı yapıda karıştırmak, her grubun aradığı bilgiyi bulmakta güçlük çekmesine yol açar.

Dört yaygın kullanıcı tipi ve bunların yapısal karşılıkları şu şekilde özetlenebilir: Ürünü ilk kez keşfedenler için adım adım başlangıç kılavuzları gerekir; bu sayfalar sıralıdır, varsayımlar asgari düzeyde tutulur ve kullanıcı başarıya hızla ulaştırılır. Belirli bir görevi tamamlamak isteyenler için pratik "nasıl yapılır" kılavuzları daha uygundur; bu sayfalar ön koşulları netleştirir, adımları numaralandırır. Teknik referans arayan geliştiriciler için API dokümantasyonu, parametre tabloları ve tip bilgileri içeren referans sayfaları gereklidir. Ürünün nasıl çalıştığını anlamak isteyenler için ise kavramsal açıklama sayfaları — mimari belgeler, terimler sözlüğü, tasarım kararlarını açıklayan metinler — ayrı bir bölümde yer almalıdır.

Bu dört tip birbirine karışmamalıdır. Aynı sayfada kılavuz ve referans bilgisi bir arada bulunursa, her iki kullanıcı tipi de aradığını bulmakta güçlük çeker. "Kimlik Doğrulama" başlığı altında hem "nasıl yapılandırılır" adımları hem de tüm JWT parametrelerinin tam listesi bulunuyorsa, ne rehber arayan ne de referans arayan kullanıcı tam olarak tatmin olur. Bu ayrım, bilgi mimarisi kurulurken yapılan temel taksonomik karardır.

Navigasyon dokümantasyonda hem yapıyı hem sırayı taşır

Dokümantasyon sitelerinde navigasyon üç ayrı katmandan oluşur: sol kenar çubuğu (sidebar), üst navigasyon (global nav) ve sayfa içi navigasyon (in-page nav). Bu üç katmanın birbirini nasıl tamamlayacağı ve hangisinin ne işlevi üstleneceği, sitenin kullanılabilirliğini doğrudan belirler.

Sol kenar çubuğu ana yapıyı taşır. Kullanıcı hangi bölümde olduğunu, o bölüm içindeki tüm sayfaları ve mevcut konumunu buradan anlar. Sidebar'ın sayfa ile birlikte aşağı kaymadan sabit kalması — yani "sticky" davranışı — dokümantasyon UX'inde neredeyse standart hale gelmiştir. Çünkü kullanıcı uzun bir sayfayı okurken bile bölüm bağlamını kaybetmek istemez; neye baktığını ve sırada ne olduğunu görebilmek ister. Sidebar derinliği genellikle iki düzeyde tutulur: bölüm başlığı ve sayfa adı. Üç veya dört düzey derin bir sidebar, ne kadar iyi düzenlenmiş olursa olsun görsel olarak bunaltıcı hale gelir.

Üst navigasyon bölümler arası geçişi yönetir. "Başlangıç", "Kılavuzlar", "Referans", "API", "Örnekler" gibi üst düzey kategoriler buraya yerleştirilir. Bu kategoriler genellikle 3–6 öğeden fazla olmamalıdır; daha kalabalık bir üst navigasyon kullanıcıyı hangi bölümün ne içerdiği konusunda kararsız bırakır. Navigasyon menüsünün yapısal tasarımı bu kararı doğrudan etkiler; özellikle kategori adlarının kullanıcı hedefine göre mi yoksa içerik türüne göre mi belirleneceği sorusu burada kritik hale gelir.

Sayfa içi navigasyon ise uzun sayfalar için "içindekiler" bölümü sunar. Bu bölüm genellikle sayfanın sağ tarafında sabit konumda durur ve kullanıcı sayfada aşağı kaydıkça mevcut başlığı vurgular. Üç katlı bu navigasyon sistemi, kullanıcının hem makro düzeyde (hangi bölümdeyim?) hem de mikro düzeyde (bu sayfanın hangi kısmındayım?) konumunu bilmesini sağlar. Üç katmanın uyumlu çalışması, tek başına hiçbirinin sağlayamayacağı bir yönelim güvencesi verir.

Arama, dokümantasyon sitelerinde navigasyonun yerini alabilir

Blog veya kurumsal sitelerde arama destekleyici bir özelliktir; kullanıcı isterse gezinerek de aradığını bulabilir. Dokümantasyonda ise arama çoğu zaman birincil yoldur. Deneyimli kullanıcılar navigasyona bakmadan doğrudan arama kutusuna gider; belirli bir fonksiyon adını, parametre ismini veya karşılaştıkları hata mesajını arar. Bu durum, aramanın dokümantasyon sitelerinde farklı biçimde konumlanması gerektiğini gösterir.

Genel bir arama altyapısı dokümantasyon ihtiyaçları için yeterince hassas sonuçlar üretemeyebilir. "useEffect cleanup" veya "rate limit headers" gibi teknik terimler bağlamıyla birlikte anlaşılmalıdır; aksi halde arama motoru bunları genel kelimeler olarak değerlendirir ve ilgisiz sonuçlar döndürür. Dokümantasyon odaklı arama çözümleri bu ihtiyacı karşılamak için özelleştirilmiştir ve başlık ağırlıklandırması, içerik parçalama ve teknik terim eşleştirmesi gibi mekanizmalar içerir. Sitenin arama fonksiyonunun entegrasyonu belge hacmi artmadan önce yapılandırılmalıdır; çünkü indeksleme yapısını sonradan değiştirmek tüm içerik tabanını etkiler.

Aramanın bir diğer boyutu sonuç sayfasının düzenidir. Dokümantasyon aramasında kullanıcı bir sayfanın başlığını değil, o sayfa içindeki belirli bir paragrafı arıyor olabilir. Bu yüzden sonuçların sayfa başlığının yanı sıra ilgili pasajı da göstermesi beklenir. Sonuç yalnızca "Yapılandırma Kılavuzu" başlığını gösterirse, aranan konfigürasyon parametresinin gerçekten o sayfada olup olmadığı belli olmaz. Pasaj önizlemesi bu belirsizliği ortadan kaldırır.

Sürüm yönetimi URL yapısında nasıl çözülür?

Ürün versiyonları değiştikçe dokümantasyon da değişir. Bir özellik v1'de bir şekilde, v2'de farklı bir şekilde çalışıyorsa her ikisinin de erişilebilir kalması gerekebilir; özellikle eski sürüme bağımlı kullanıcılar hâlâ sistemlerini çalıştırıyorsa bu durum zorunluluk haline gelir. Bu gereksinim, URL yapısında sürüm bilgisinin nasıl taşınacağı sorusunu gündeme getirir.

Yaygın yaklaşım URL'ye sürüm öneki eklemektir: /docs/v1/kurulum ve /docs/v2/kurulum. Bu yapı açık, anlaşılır ve bookmarklanabilirdir. Dezavantajı, her büyük sürüm güncellemesinde tüm içerik ağacının kopyalanmasını gerektirmesidir; ayrıca aynı konuyu iki sürümde de güncel tutmak ek editoryal yük yaratır. Alternatif bir yaklaşımda aktif sürüm /docs/kurulum gibi sürümsüz bir URL üzerinden sunulur; eski sürümler ise /docs/v1/ alt dizininde arşivlenir. Bu yaklaşım URL yapısının planlanması açısından daha temiz bir denklem sunar.

Bazı ekipler sürüm seçimini URL yerine subdomain düzeyinde çözer: v1.docs.ornek.com. Bu yaklaşım URL yapısını kısa tutar ama çapraz sürüm bağlantıları karmaşıklaşır ve kullanıcı hangi sürümde olduğunu bazen URL bazen de domain üzerinden anlamak zorunda kalır. Hangi yol seçilirse seçilsin, eski sürümlere erişim kalıcı olarak kesilmemelidir. Kullanıcıların önemli bir bölümü platform geçişlerinde eski dokümantasyona hâlâ başvurur; bu sayfalar silinirse destek yükü kaçınılmaz biçimde artar.

Dokümantasyon büyüdükçe kategori sınırları kayar

Küçük bir dokümantasyon sitesi beş ya da altı başlıkla başlayabilir. İçerik büyüdükçe bu başlıklar dolup taşar ve yeni ara kategoriler açılır. Bir süre sonra "Gelişmiş Konular", "Diğer" veya "Çeşitli" gibi başlıklar belirmeye başlar. Bunlar büyüyen ama sınıflandırılamayan içeriklerin deposu haline gelir ve yapının çöküşünü işaret eder.

Bu kayma, içerik hiyerarşisinin baştan çok sıkı ya da çok gevşek kurulmasından kaynaklanır. Çok sıkı kurulmuş bir yapı yeni içerikleri bünyesine almakta zorlanır; her ekleme bir "bu nereye gidecek?" sorusunu doğurur. Çok gevşek kurulmuş bir yapı ise zamanla kategoriler anlamsız birer kap haline gelir ve kullanıcı neyin nerede olduğunu tahmin edemez.

Pratik çözüm, kategori başlıklarını içeriğin özelliğiyle değil, kullanıcının hedefiyle tanımlamaktır. "Gelişmiş API" bir kategori adı değildir; içeriğin karmaşıklık düzeyini tanımlar ama kullanıcının amacını söylemez. "Entegrasyon Kurulumu", "Kimlik Doğrulama", "Webhook Yapılandırması" ise kullanıcının ne yapmak istediğini ortaya koyar. Bu isimlendirme prensibi, kategori sınırlarının içerik büyüdükçe korunmasını kolaylaştırır; çünkü yeni bir sayfa eklendiğinde "bu hangi kullanıcı hedefine karşılık geliyor?" sorusu doğal bir yerleştirme kılavuzu işlevi görür.

İçerik modeli olmadan başlanan dokümantasyon zamanla onarılması güç bir hal alır

İçerik modeli, her sayfa tipinin hangi bileşenlerden oluşacağını tanımlar. Bir "Nasıl Yapılır" sayfasının giriş, ön koşullar, numaralı adımlar ve beklenen sonuç bölümlerini içermesi; bir "Referans" sayfasının parametre tablosu, veri tipi, varsayılan değer ve örnek kod bloğunu içermesi gerekebilir. Bu şablon, her içerik tipinin tutarlı biçimde kurgulanmasını sağlar.

Model olmadan üretilen dokümantasyonda her yazar farklı bir format kullanır. Bazı sayfalar kod örneğiyle açılır, bazıları kavramsal açıklamayla, bazıları doğrudan adımlarla. Kullanıcı aynı sitenin farklı bölümlerinde farklı bir deneyimle karşılaşır ve nerede ne bulacağını öngöremez. Bu öngörülemezlik, arama dışında gezinmeyi neredeyse imkânsız hale getirir.

İçerik modeli oluşturma sürecinde site haritası planlaması da devreye girer. Hangi sayfa tiplerinin bulunacağı, bu tiplerin URL yapısındaki karşılığı ve birbirleriyle ilişkisi, site haritası üzerinde görünür hale geldiğinde mimari tutarsızlıklar erken fark edilir. "Kavramsal açıklama" sayfası mı, "nasıl yapılır" kılavuzu mu yoksa "referans belgesi" mi üreteceğimizi bilmeden başlamak, ilerleyen süreçte yeniden yazma döngüsünü kaçınılmaz kılar.

Dokümantasyon sitesi kurmak, içerik üretmekten önce yapısal bir karar süreci gerektirir. Kullanıcı tiplerini netleştirmek, sayfa tiplerini ayırt etmek, navigasyon katmanlarını doğru yapılandırmak ve URL yapısını sürüm senaryolarına hazır biçimde planlamak, içerik büyüdükçe yükü azaltan adımlardır. Bu kararlar baştan yapılmadığında, genellikle en kötü anda — sitenin karmaşıklaştığı, kullanıcı şikayetlerinin arttığı ya da büyük bir platform geçişi zorunlu hale geldiği anda — yüzleşilmek zorunda kalınır.

Bir dokümantasyon sitesinin kalitesi, içeriğin bilgi yoğunluğuyla değil, kullanıcının aradığına ne kadar hızlı ulaşabildiğiyle ölçülür. Yapı bu hızı ya mümkün kılar ya da engeller.