API Belgeleri ve Değişiklik Kayıtları için Web Uygulaması Nasıl Oluşturulur

Hedefleri ve Kullanıcıları Tanımlayın

Özellikleri seçmeden veya teknoloji yığınını belirlemeden önce bu uygulamanın kime hizmet edeceğini ve neden var olması gerektiğini netleştirin. API belgeleri ve değişiklik kayıtları, doğru insanların doğru cevapları hızlıca bulmasına yardımcı olduğunda “iyi” olur.

Birincil hedef kitlenizi tanımlayın

Kullanacak (veya etkilenecek) grupları adlandırarak başlayın:

• Dahili ekipler (mühendislik, destek, ürün): tek bir doğruluk kaynağına ve güncellemeleri hızlı yayınlamaya ihtiyaç duyar.\
• Partnerler: stabil dokümantasyon, net erişim kontrolleri ve öngörülebilir sürüm iletişimi ister.\
• Herkese açık geliştiriciler: kolay keşif, güvenilir versiyonlama ve basit yükseltme rehberliği ister.

Herkes için eşit şekilde optimize etmeye çalışırsanız, muhtemelen kafa karıştırıcı bir ilk sürüm çıkarırsınız. Bir birincil kitle seçin ve diğerlerini açıkça ikincil kabul edin.

Gerçek ağrı noktalarını yakalayın

Çözdüğünüz spesifik problemleri, yakın dönem olaylardan örneklerle yazın:

Dağınık belgeler (wiki'ler ve repo'lar arasında), Slack'te paylaşılıp saklanmayan sürüm notları, net bir kullanım dışı bırakma politikası olmadan değişen endpoint'ler, birden fazla “latest” versiyon veya “bunun nerede yazdığı” sorusuna dönüşen destek biletleri.

Bunları doğrulayabileceğiniz ifadelere dönüştürün, örneğin:

• “Geliştiriciler hangi sürüme yönelik olduğunu bilemiyor.”
• “Destek, müşterilere kanonik bir değişiklik kaydı girdisi bağlayamıyor.”

Ölçülebilir başarı metrikleri belirleyin

Sonuçlarla bağlantılı küçük bir metrik seti seçin:

• Yayımlama süresi (taslak → onay → canlı)
• Tekrarlayan destek sorularında azalma (etiket bazlı biletler)
• En son sürümün benimsenmesi (en son doküman trafiği, yükseltme tamamlanması)

Bunları nasıl ölçeceğinizi tanımlayın (analitikler, bilet etiketleri, dahili anket).

Erişim kararını verin: herkese açık, özel veya karma

Birçok ekip karma erişime ihtiyaç duyar: çekirdek endpoint'ler için kamuya açık belgeler, partner-özel özellikler için özel belgeler ve destek için dahili notlar.

Eğer karma erişim bekliyorsanız, bunu birinci sınıf bir gereksinim olarak ele alın—içerik yapınız ve izin modeli buna bağlı olacaktır.

MVP için “bitti” tanımını yapın

İlk sürümün neyi başarması gerektiğini netleştirin. Örneğin:

“Destek, sürümlenmiş belgelere ve insan tarafından okunabilir bir değişiklik kaydına stabil bir bağlantı paylaşabilmeli ve ürün ekibi bir iş günü içinde yayımlama yapabilmeli.”

Bu tanım, sonraki bölümlerde vereceğiniz tüm takasları yönlendirecektir.

MVP için Özellikleri Seçin

Bir API dokümantasyon uygulaması için MVP, bir şeyi kanıtlamalı: ekibiniz doğru belgeleri ve değişiklik kayıtlarını hızlıca yayımlayabiliyor ve okuyucular değişiklikleri güvenilir şekilde bulabiliyor. Önce çekirdek yayımlama döngüsünü destekleyen özellikleri seçin; kolaylıkları yalnızca doğrudan sürtünmeyi azaltıyorsa ekleyin.

Olmazsa olmaz özellikler (önce bunları gönderin)

Gerçek dokümantasyonu ve gerçek sürümleri destekleyen en küçük kümeye odaklanın:

• Sayfalar: taslak ve yayımlanmış durumlu bir doküman hiyerarşisi (ör. Overview → Guides → Reference).\
• Değişiklik kaydı girdileri: başlık, tarih, tür (Added/Changed/Fixed/Deprecated) ve etkilenen endpoint'lerle yapılandırılmış gönderiler.\
• Versiyon etiketleri: sayfalara ve değişiklik girdilerine versiyon (veya tarih tabanlı sürüm) iliştirin, böylece kullanıcılar kendilerine uygulananları filtreleyebilir.\
• Arama: sayfa başlıkları, başlıklar ve değişiklik kaydı metni üzerinde hızlı, affedici arama.\
• Roller: en azından Admin, Editor ve Viewer; böylece değişiklikler tek kişide takılmasın.

İçerik ihtiyaçları (insanlar gerçekten kullansın diye)

Markdown genellikle yüksek kaliteli teknik içeriğe hızlı erişim sağlarken editör dostu kalmanın en çabuk yoludur.

Editörünüzün desteklediğinden emin olun:

• Markdown ile önizleme
• Kod blokları için sentaks vurgulama
• Tablolar (parametreler, hata kodları için)
• Temel dosya yönetimi (şemalar, UI ekran görüntüleri gibi varlıklar)

Olması iyi ama erteleyin (çekirdek döngü çalışana kadar)

Erken aşamada aşırı geliştirilebilecek ama değerli olanlar:

• Satır içi yorumlar veya “önerilen düzenlemeler” işbirliği için
• Analitik (en çok okunan sayfalar, başarısız aramalar) iyileştirme için
• Webhooks (Slack bilgilendirmesi, dahili araç tetikleme)\
• Çoklu ürün desteği gerçekten ayrı API'leriniz varsa

Fonksiyonel olmayan gereksinimler (erken beklentileri koyun)

Sonradan yeniden mimari yapmamak için hedefleri şimdi yazın:

• Çalışma süresi hedefi (ör. %99.9) ve yedekleme/kurtarma beklentileri
• Performans hedefleri (arama sonuçları \u003c 300ms, sayfa yüklemeleri ort. \u003c 2s)
• Erişilebilirlik tabanı (navigasyon ve editör UI için WCAG 2.1 AA hedefi)

Uyumluluk ve güvenlik (ilgiliyse, ama baştan karar verin)

Daha büyük kuruluşlara satıyorsanız planlayın:

• Denetim izi (kim neyi, ne zaman değiştirdi)
• Saklama kuralları (silinmiş içerik için)
• SSO (SAML/OIDC) ve zorunlu MFA

Emin değilseniz, denetim kaydını “şimdi küçük, sonra vazgeçilmez” olarak kabul edin.

Mimari ve Teknoloji Yığını Planlayın

Temiz bir mimari, her şeyi kolaylaştırır: doküman düzenleme, yayımlama, arama ve bildirim gönderme. API dokümanları + değişiklik kaydı uygulaması için ilk sürümü basit tutup büyümeye alan bırakabilirsiniz.

Basit, ölçeklenebilir bir temel

Dört yapı taşıyla başlayın:

• Web frontend: doküman yazma, versiyonlara göz atma ve değişiklikleri inceleme UI'sı.\
• Backend API: kimlik doğrulama, izinler, iş akışı durumu ve içerik sorguları.\
• Veritabanı: kullanıcılar, projeler, doküman meta verisi, versiyonlar, inceleme durumu ve değişiklik kaydı girdileri.\
• Dosya/nesne depolama: büyük varlıklar (ekler, dışa aktarımlar) ve isteğe bağlı olarak render edilmiş HTML.

Bu ayrım, bağımsız ölçeklenmeyi sağlar: ağır bir arama veya render işi editörü yavaşlatmamalıdır.

Yığını seçmek (ve nasıl karar verilir)

Birkaç iyi seçenek var; en iyi seçim genellikle ekibinizin güvenle gönderebileceği ve bakımını yapabileceği olandır.

• Node.js (Express/NestJS): web uygulamaları için güçlü ekosistem; Markdown araçları; gerçek zamanlı özellikler kolay.\
• Python (FastAPI/Django): hızlı inşa, güçlü tip desteği ve arka plan işi desteği.\
• Ruby on Rails: CRUD geliştirmede hızlı; iş akışları ve admin panelleri oluştururken konvansiyonlar yardımcı.

Ön uç için SEO-dostu doküman sayfaları ve akıcı bir editör deneyimi açısından React/Next.js yaygın bir tercihtir.

Eğer hızlıca çalışan bir portal kurmak istiyorsanız (ve yine de gerçek kaynak kodu almak istiyorsanız), Koder.ai gibi bir hızlandırıcı platform pratik olabilir. Sohbette doküman iş akışlarını ve izin kurallarını tarif ederek React frontend ile Go backend (PostgreSQL) oluşturabilir ve uygulama detaylarına başlamadan önce “planlama modunda” iterasyon yapabilirsiniz.

Dokümanlarınız “nerede yaşar”?

Erken karar verin, çünkü bu ileride versiyonlama ve iş akışını etkiler:

• Veritabanı-tabanlı: WYSIWYG/Markdown editörleri ve izinler için en kolay yol.\
• Git-tabanlı: geliştirici ekipleri ve PR incelemeleri için mükemmel.\
• Hibrit: taslaklar için veritabanı + uzun vadeli geçmiş için Git dışa/ithal.

Ortamlar ve gelecekteki entegrasyonlar

Gün birinci günden local → staging → production planlayın, staging minimal olsa bile. Ayrıca muhtemel entegrasyonları (spec doğrulamak için CI, onaylar için ticket sistemi, sürüm uyarıları için chat) listeleyin ki ileride sizi engelleyecek seçimlerden kaçının.

Veri Modelini Tasarlayın

Temiz bir veri modeli dokümanlarınızı, değişiklik kayıtlarınızı ve izinleri kullanıcılar için “açık” hissettiren şeydir. Birden fazla ürün/API, öngörülebilir yayımlama durumları ve izlenebilirlik destekleyen bir şema hedefleyin.

Temel varlıklar

Çoğu API dokümantasyon uygulaması şu yapı taşlarıyla başlayabilir:

• Product: üst seviye gruplayıcı (ör. “Payments”).\
• API: bir product içindeki belirli arayüz (ör. “Checkout API”).\
• DocPage: gerçek içerik birimleri (kılavuzlar, referans sayfaları, öğreticiler).\
• Version: semantik versiyon veya tarih tabanlı sürüm kimliği.\
• ChangelogEntry: genellikle bir API/product ile ve genelde bir Version ile ilişkilendirilen tek bir değişiklik girdisi.\
• User, Role: kişiler ve erişim seviyeleri.

Gezilebilirliği koruyan ilişkiler

İçeriği, yaygın soruları kolay cevaplayacak şekilde modelleyin:

• Bir Product birçok API içerir.\
• Bir API birçok DocPage ve birçok ChangelogEntry içerir.\
• Bir ChangelogEntry, bir Version ile (opsiyonel olarak etkilenen belirli DocPage'lere) bağlanır.

DocPage'ler genellikle hiyerarşi ister. Basit bir yaklaşım parent_id (ağaç) artı sıralama için position alanıdır. Büyük ağaçlar ve sık yeniden sıralama beklentisi varsa baştan özel bir sıralama stratejisi (ör. sortable list) düşünün.

Kaydetmeye değer meta veriler

Her DocPage ve ChangelogEntry için saklayın:

• status: draft / in_review / published
• tags: filtreleme ve keşif için
• visibility: public vs internal vs partner
• owners: bir veya daha fazla sorumlu kullanıcı/ekip

Denetim izi ve ekler

Sorumluluğu bir denetim günlüğüyle takip edin: actor_id, action, entity_type, entity_id, before, after, created_at.

Ekler için nesne depolama (S3/GCS/Azure Blob) tercih edin ve DB'de yalnızca meta veri saklayın (URL, mime type, boyut, checksum). Büyük ikili dosyaları veritabanından uzak tutmak genellikle performansı iyileştirir ve yedeklemeleri basitleştirir.

Kimlik, Roller ve İzinleri Kurun

Kimlik doğrulama ve yetkilendirme, dokümanlarınızın ve değişiklik kayıtlarınızın güvenli bir şekilde yönetilmesini belirler. İçerik ve ekipler ölçeklendikçe kuralları sonradan düzeltmemek için bunları erken doğru kurgulayın.

Rolleri tanımlayın (ve neler yapabildiklerini)

Küçük, net bir rol setiyle başlayın:

• Reader: yayımlanmış dokümanları, değişiklik kayıtlarını ve sürüm notlarını görüntüleyebilir.\
• Editor: taslak oluşturup düzenleyebilir (doküman sayfaları, değişiklik girdileri) ama yayımlayamaz.\
• Reviewer: yorum yapabilir, değişiklik isteyebilir ve yayın için onay verebilir.\
• Admin: kullanıcıları yönetir, ayarları yapılandırır ve iş akışı kilitlerini geçersiz kılabilir.

İzinleri UI ekranlarına değil (create/edit/approve/publish/archive gibi) aksiyonlara bağlayın; bu kuralların denetlenmesini ve test edilmesini kolaylaştırır.

Hedef kitlenize uyan kimlik doğrulamayı seçin

Yaygın seçenekler:

• Email/şifre: gönderimi en basit olan; güvenli parola saklama (bcrypt/argon2) ve parola sıfırlama akışları gerekir.\
• OAuth (Google, GitHub): dış katkıda bulunanlar ve geliştirici toplulukları için iyi.\
• SSO/SAML: kurumsal satış düşünülüyorsa merkezi kimlik için düşünün.

Uygulamanız birden fazla şirket tarafından kullanılacaksa kuruluş/çalışma alanı üyeliği için baştan tasarlayın.

Geçmişinizi koruyan yetkilendirme kuralları

Doküman sistemleri genellikle eski versiyonların sessizce yeniden yazılmasıyla başarısız olur. Açık kurallar ekleyin:

• Yalnızca Admin'ler (veya özel “Maintainer” rolü) yayımlanmış içeriği düzenleyebilir.\
• Eski versiyonlar salt okunur olmalıdır; bir admin yeni bir patch versiyon oluşturana kadar değiştirilemez.\
• Yalnızca Reviewer/Admin onaylayabilir; yalnızca Admin'ler (veya atanmış yayımlayıcılar) yayımlayabilir.

Bu kuralları yalnızca frontend'de değil API seviyesinde modelleyin.

Güvenlik temelleri ve içerik güvenliği

Oturumları secure, httpOnly cookie ile koruyun, kısa ömürlü token'lar ve uygun çıkış akışları kullanın. Cookie tabanlı oturumlar için CSRF koruması ekleyin. Giriş, parola sıfırlama ve yayın uç noktalarına rate limiting uygulayın.

Son olarak, dokümantasyonu güvenilmeyen girdiler olarak ele alın. HTML/Markdown çıktısını sanitize edin ve script enjeksiyonunu (XSS) engelleyin. Embed destekliyorsanız izinli bir liste ve güvenli render varsayılanları kullanın.

Dokümantasyon Editör Deneyimini Kurun

Bir doküman platformu, editörüyle ayakta durur veya yıkılır. Amacınız yazmayı hızlı, öngörülebilir ve güvenli hissettirmek—yazarlar düzenlerken okurun göreceğiyle eşleştiğine güvenmeli.

Doğru editörü seçin (Markdown, zengin metin veya ikisi)

Çoğu API ekibi Markdown-öncelikli bir editörden fayda sağlar: hızlıdır, diff-dostudur ve versiyonlama ile iyi çalışır. Yine de bazı katkıda bulunanlar tablolar, callout'lar ve biçimlendirme için zengin metin tercih eder.

Pratik bir yaklaşım çift moddir:

• Güç kullanıcıları için Markdown modu\
• Ara sıra katkı yapanlar için Zengin-metın modu\
• Tek bir temel format (Markdown sakla, HTML'e render et) uyumsuzlukları önler

Önizlemeyi son sayfa gibi hissettirin

Üretimde kullanılan aynı bileşenler, fontlar ve boşluklarla sayfayı render eden bir canlı önizleme ekleyin. Editöre özel UI'yi gizleyen ve gezinme/yan panelleri gösteren “Okur olarak önizle” geçişi ekleyin.

Önizlemeyi tutarlı kılın:

• kod vurgulama\
• callout'lar (Not/Uyarı)\
• tablolar ve responsive düzen\
• endpoint blokları gibi gömülü bileşenler

Kopyala-yapıştır yerine yeniden kullanılabilir bloklar kullanın

Herkes aynı desenleri elle yazdığında tutarsızlık olur. Yazarların ekleyebileceği yeniden kullanılabilir bileşenler sağlayın:

• Kod örnekleri (dil sekmeleri, kopyala düğmesi)\
• Endpoint blokları (metod, yol, auth, örnek istek/yanıt)\
• Parametre tabloları (isim, tip, zorunlu, açıklama)

Bu, formatlama hatalarını azaltır ve güncellemeleri merkezi hale getirir.

Bağlantı kurallarını tanımlayın (ve uygulayın)

İç bağlantılar kolay ve güvenilir olmalı:

• Diğer sayfalara otomatik tamamlama (ör. /docs/authentication)\
• Değişiklik kaydı girdilerine doğrudan bağlanmaya izin verin (ör. /changelog/2025-10-14)\
• Yayımlamadan önce kırık linkler konusunda uyarı verin

Anchor destekliyorsanız, başlıkların beklenmedik şekilde “hareket etmemesi” için tutarlı anchor üretin.

Hafif bir stil rehberi oluşturun

Editörden erişilebilen kısa bir stil rehberi ekleyin (ör. /docs/style-guide) ve şunları kapsasın:

• başlık hiyerarşisi ve adlandırma (bölümler için H2, alt bölümler için H3)\
• ton (açık, etkin cümle, alaydan kaçın)\
• örnekler (her zaman bir başarı örneği; yaygınsa hata örneği)

Buradaki küçük kısıtlamalar sonraki büyük temizlik işlerini önler.

Versiyonlama ve Kullanımdan Kaldırma Kurallarını Uygulayın

Versiyonlama, API dokümanlarını “bir dizi sayfa” olmaktan güvenilir bir sözleşme haline getirir. Uygulamanız neyin güncel olduğunu, ne değiştiğini ve neyin artık güvenli olmadığını açıkça göstermeli.

Bir versiyonlama modeli seçin

İki yaygın yaklaşım iyi işler:

• Sayfa-başı versiyonlar: her sayfanın kendi geçmişi olur. Hızla değişen ürünler için esnektir ama farklı sayfaların farklı versiyonlarda olması riski vardır.\
• Sürüm anlık görüntüleri: her sürüm tüm doküman setinin donmuş bir anlık görüntüsünü oluşturur (tek bir sayfa değişse bile). Bu, kullanıcılar için daha basittir: “v1.4 belgeleri” her zaman “API v1.4” ile eşleşir.

API'niz bütünüyle versiyonlanıyorsa, anlık görüntüler genelde kafa karışıklığını azaltır. Farklı ekipler bağımsız olarak değişiklik yayımlıyorsa, sayfa-başı versiyonlama daha pratik olabilir.

URL kuralları: latest vs pinned

Her iki gezinme stilini destekleyin:

• Latest: çoğu okuyucu için /docs/latest/...\
• Pinned: stabiliteye ihtiyaç duyan müşteriler için /docs/v1/..., /docs/v1.4/...

“latest” bir işaretçi olsun, kopya değil. Böylece sabitlenmiş linkler bozulmadan güncelleme yapabilirsiniz.

Yeni bir sürüm ne tetikler?

Yazarların tahmin etmemesi için uygulamaya açık kurallar yazın:

• Yeni sürüm: kırıcı değişiklikler, kaldırılan/yeniden adlandırılan alanlar, değişen auth gereksinimleri, yeni zorunlu parametreler, davranış değişiklikleri.\
• Patch notu: yazım düzeltmeleri, örnekler, açıklamalar, kırmayan eklemeler.

Yayımlama sırasında basit bir uyarı uygulayın: “Bu bir kırıcı değişiklik mi?” ve zorunlu bir gerekçe alanı.

Kullanımdan kaldırmaları tutarlı ele alın

Kullanımdan kaldırma, sadece uyarı paragrafı değil yapılandırılmış olmalı.

Açık alanlar ekleyin:

• Deprecated in (versiyon/tarih)\
• Removal date veya removed in versiyon\
• Replacement (yeni endpoint/sayfaya bağlantı)

Etkilenen sayfalarda bir afiş gösterin ve kullanımdan kaldırmaları değişiklik kayıtlarında ve sürüm notlarında görünür kılın.

Mevcut dokümanlardan geçiş planlayın

Geçişi bir geçmiş içe aktarma olarak ele alın:

• Mevcut etiketleri/branch'leri versiyon modelinize eşleyin.\
• Eski değişiklik kayıtlarını sabitlenmiş sürümler olarak içe aktarın (kusurlu olsa bile).\
• Bir temiz “vNext/latest” ile başlayın ve müşterilerin hâlâ kullandığı versiyonları arkadan doldurun.

Bu, her şeyi yeniden yazmadan birinci günden kullanılabilir versiyonlama sağlar.

Yayımlama ve İnceleme İş Akışını Oluşturun

Net bir iş akışı, bozuk dokümanları, kazara yayımlamaları ve “bunu kim değiştirdi?” kafa karışıklığını önler. Doküman sayfalarını ve değişiklik girdilerini tahmin edilebilir durumlar arasında hareket eden içerik olarak ele alın; her adımda görünür sahiplik olsun.

Durumları ve sorumlulukları tanımlayın

Herkesin anlayacağı basit bir durum makinesi kullanın: draft → in review → approved → published.

• Draft: yazar serbestçe düzenleyebilir; kamuya görünmez.\
• In review: değişiklikler gözden geçirme düzeltmeleri dışında dondurulur; gözden geçirenler bildirilir.\
• Approved: yayımlamaya hazır; opsiyonel son kontroller (linkler, biçimlendirme, zorunlu meta) çalıştırılabilir.\
• Published: kullanıcılara görünür; değişiklik yapmak için yeni bir taslak gerekir.

Pratik inceleme araçları ekleyin

İncelemeler hızlı ve spesifik olmalı. Şunları dahil edin:

• Render edilmiş sayfa üzerinde veya diff görünümünde satır içi yorumlar\
• Değişiklik istekleri (onay bloklanana kadar)\
• Kontrol listeleri (örnek: “auth bölümü güncellendi”, “kod örneği çalışıyor”, “kırıcı değişiklik işaretlendi”)

Arayüz hafif tutun: bir gözden geçirenin dakika içinde onay verebilmesi, başka bir bilet açmak zorunda kalmaması iyi bir işarettir.

Yüksek etkili içerikler için onay kapıları kurun

Kamuya açık sayfalar ve sürümler için en az bir gözden geçiren (veya “Docs Maintainer” gibi bir rol) gerekli kılın. Kapı kurallarını alan/ekibe göre yapılandırılabilir tutun ki dahili belgeler daha az aşamalı yayımlanabilsin.

Zamanlama ve hızlı geri alma desteği verin

Yazarların hemen yayımla veya gelecek bir tarih/saatte yayımla seçmesine izin verin (zaman dilimi dahil). Geri alma için, önceki yayımlanmış versiyona geri dönmek tek tıkla mümkün olsun—özellikle bir sürüme bağlı değişiklik girdileri için. Geri alma ile birlikte denetim notu bırakmayı zorunlu kılın.

Koder.ai üzerinde inşa ediyorsanız, platformun kendi yaklaşımlarını örnek alın: anlık görüntüler ve geri alma hızlı iterasyon için kanıtlanmış bir UX modelidir ve doküman yayımlamada da iyi işler.

Değişiklik Kaydı ve Sürüm Notları Sistemini Tasarlayın

Bir değişiklik kaydı yalnızca iki soruyu hızlı cevaplıyorsa kullanışlıdır: ne değişti ve beni etkiler mi? En iyi sistemler tutarlı bir yapı zorlar, değişiklikleri dokümanlara bağlar ve güncellemeleri tüketmenin birden fazla yolunu sunar.

Standart bir yapı ile başlayın

Gönderileri taraması kolay ve filtrelemesi basit bir taksonomi kullanın. Pratik bir varsayılan:

• Added: yeni endpoint'ler, alanlar, SDK metodları, yeni kılavuzlar\
• Changed: davranış değişiklikleri, yeniden adlandırılan parametreler, yeni varsayılanlar\
• Fixed: hata düzeltmeleri, yanlış doküman düzeltmeleri (bunları açıkça belirtin)\
• Deprecated: hala çalışıyor ama ileride kaldırılacak\
• Removed: artık kullanılamıyor\
• Security: auth değişiklikleri, güvenlik düzeltmeleri, gerekli yükseltmeler

Her madde küçük, tamamlayıcı birimler olsun: ne değişti, nerede, etki ve sonraki adım.

Gönderileri tutarlı tutmak için şablonlar kullanın

Kategori başına bir “Yeni değişiklik girdisi” formu sağlayın. Örneğin, Changed şablonu şunları içerebilir:

• Özet (bir cümle)
• Etkilenen endpoint'ler / kaynaklar\
• Kırıcı değişiklik? (Evet/Hayır)\
• Geçiş adımları\
• Bağlantılar (doküman sayfaları, referans endpoint'ler, ticket'lar)

Şablonlar inceleme sürecini azaltır ve farklı yazarlar arasında bile sürüm notlarını tutarlı hissettirir.

Değişiklikleri dokümanlara ve endpoint'lere bağlayın

Değişiklik girdileri sadece metin olmasın—izlenebilir olsun. Yazarların iliştirmesine izin verin:

• Güncellenen doküman sayfası(ları) (ör. /docs/authentication)\
• Belirli endpoint/referans düğümleri (ör. POST /v1/payments)\
• İlgili versiyonlar (doküman versiyonu ve API versiyonu)

Böylece “Bu sayfa 2025.12 sürümünde güncellendi” bilgisini doküman sayfasında gösterebilir ve bir değişiklik girdisi otomatik olarak etkilediği sayfaları/endpoint'leri listeleyebilir.

“Benim için ne değişti” görünümü sunun

Kullanıcılar nadiren tüm geçmişi ister. Kendi sürümleri ile hedef sürümü karşılaştıran ve sadece ilgili maddeleri özetleyen bir görünüm ekleyin:

• Önce kırıcı değişiklikler\
• Kullandıkları endpoint'leri etkileyen değişiklikler (abonelikler veya kaydedilmiş endpoint'lere göre filtrelenmiş)\
• Zaman çizelgeli kullanımdan kaldırmalar

Basit bir sürümler arası karşılaştırma ve iyi filtreleme, uzun bir değişiklik kaydını harekete geçirilebilir bir yükseltme planına dönüştürür.

Dışa aktarımlar ve feed'ler sunun

Farklı ekipler güncellemeleri farklı takip eder; bu yüzden birkaç çıktı sağlayın:

• Ürün/versiyon veya etiket başına RSS/Atom feed'i\
• Panolar ve dahili araçlar için JSON feed\
• E-posta hazır format (konu, giriş, gruplanmış bölümler)

Feed URL'lerinin stabil kalmasını sağlayın ve tüketicilerin doğrudan detaylara atlaması için portal sayfalarına göreli bağlantılar kullanın.

Arama, Navigasyon ve Keşfi Ekleyin

Arama ve navigasyon, bir API dokümantasyon uygulamasını “bir dizi sayfa” olmaktan kullanılabilir bir geliştirici portalına dönüştürür. Geliştiriciler genellikle bir sorunla gelir (“Webhook nasıl oluşturulur?”) ve göreviniz onların site yapısını zaten bilmeksizin doğru cevaba hızlıca ulaşmalarını sağlamaktır.

Anlık hissi veren tam metin arama

En azından doküman sayfaları ve değişiklik/günlük girdileri üzerinde tam metin arama destekleyin. Bunları tek bir bilgi tabanı gibi ele alın ki kullanıcılar “rate limits” arayınca hem doküman sayfasını hem de limitlerin değiştiği sürüm notunu görebilsin.

Pratik bir yaklaşım, başlıklar, başlık satırları, gövde ve etiket gibi alanları indekslemek ve başlık veya başlık satırlarında eşleşen sonuçlara ağırlık vermektir. Ayrıca eşleşen terimlerin olduğu küçük bir snippet gösterin ki kullanıcılar tıklamadan doğru sonucu doğrulayabilsin.

Ekiplerin çalışma şeklini yansıtan filtreler

Arama sonuçları, kullanıcıların içeriği daraltabildiği filtrelerle daha yararlı olur. Yaygın filtreler:

• Product (veya API)\
• Versiyon (veya doküman seti)\
• Etiketler\
• Durum (draft, published, deprecated)\
• Tarih aralığı (özellikle değişiklik kayıtları için)

UI'yi kontrol yığınına çevirmeyin. İyi bir desen “önce ara, sonra daralt”tır; filtreler yan panelde ve hemen uygulanır şekilde tutulur.

Navigasyon temelleri: yan panel, breadcrumb ve ilgili sayfalar

Gezinme hem keşif hem de yön bulma desteklemeli:

• Doküman hiyerarşisini keşfetmek için yan panel ağacı, belirgin bölüm etiketleri ve “geçerli sayfa” görünümü.\
• Kullanıcıların üst bölümlere atlamasını sağlayan breadcrumblar.\
• İlgili sayfalar (ör. “Authentication”dan “Error codes”, “Rate limits” ve “SDK setup”a bağlantılar) ölü uçları azaltır.

İlgili sayfalar etiketlere, ortak üst bölüme veya manuel kürasyona göre oluşturulabilir. Teknik olmayan ekipler için manuel kürasyon genellikle en iyi sonucu verir.

Sonuçlarda kamuya/özele saygı gösterin

Arama, özel endpoint'leri veya yayımlanmamış özellikleri ortaya çıkarırsa güven bozulur. Arama indeksiniz ve sonuçlarınız görünürlük kurallarını tutarlı şekilde uygulamalı:

• Bir kullanıcı bir sayfayı görüntülemeye yetkili değilse, sonuçlarda görünmemelidir.\
• Karma erişimli organizasyonlar için indeksleme izin farkındalıklı olmalı (veya kamu ve özel içerik için ayrı indeksler tutun).\
• Snippet'lara dikkat edin: kısmi bir alıntı bile hassas detay sızdırabilir.

Kamuya açık dokümanlar için SEO gereklileri

Bölümleriniz kamuya açıksa birkaç SEO temelini baştan ekleyin:

• Benzersiz, tanımlayıcı sayfa başlıkları ve meta açıklamalar\
• Versiyonlar arasında tutarlı yapı ile stabil URL'ler\
• Versiyonlanmış dokümanlarda çoğaltılmış içerik sorununu önlemek için canonical URL kullanımı\
• Taslakları veya özel bölümleri dizine eklenmemesi için engelleme (noindex)

Arama ve keşif sadece özellik değildir—insanların doküman deneyimi budur. Kullanıcılar doğru sayfayı saniyeler içinde bulabiliyorsa, diğer tüm iş akışı özelliklerinin değeri artar.

Bildirimler ve Abonelikleri Gönderin

Bildirimler, doküman ve değişiklik kaydı uygulamanızı insanların güvendiği bir ürüne dönüştürür. Amaç daha çok mesaj göndermek değil—doğru güncellemeyi doğru kitleye net bir dönüş yolu ile ulaştırmaktır.

İnsanların neye abone olabileceğine karar verin

Ekiplerin API'leri nasıl tükettiklerine uyan kapsamlarla başlayın:

• Ürün bazlı (ör. “Payments Platform”)\
• API bazlı (ör. “Transactions API”)\
• Versiyon hattı bazlı (ör. “v1.x” vs “v2.x”)

Bu, bir müşterinin v1'de kalırken kendisini ilgilendiren güncellemeleri almasını sağlar; v2-only değişikliklerle spam olmaz.

Kanallar: e-posta, Slack ve webhook'lar

En az bir “insan” kanalı ve bir “makine” kanalı destekleyin:

• E-posta geniş erişim ve digest için\
• Slack (veya MS Teams) takım görünürlüğü için paylaşılan kanalda\
• Webhooks otomasyon için (ör. kırıcı bir değişiklik yayınlandığında Jira bileti yarat)

Her bildirim ilgili bağlama derin bağlantı içermeli: ör. /docs/v2/overview, /changelog veya belirli bir giriş (ör. /changelog/2025-12-01).

Uyarı yorgunluğunu önleyecek tercihlerin sunulması

Kullanıcılara kontrol verin:

• Frekans: anlık vs günlük/haftalık özet\
• Susturma pencereleri: geçici olarak duraklatma (tatil modu)\
• Önem filtreleri: sadece kırıcı değişiklikler veya tüm değişiklikler dahil

Basit bir varsayılan iyi çalışır: kırıcı değişiklikler için anlık, diğerleri için digest.

Keşfi destekleyen uygulama içi bildirimler

Okunmamış sayısı ve kısa sürüm özetleri gösteren bir uygulama içi gelen kutusu ekleyin ki kullanıcılar detaylara dalmadan önce nelerin değiştiğine göz atsın. “Okundu olarak işaretle” ve “Sonra kaydet” eylemleri ekleyin ve her zaman kaynak girdiye ve etkilenen doküman sayfasına bağlayın.

Uygulamayı Test Edin, Dağıtın ve Bakımını Yapın

Bir API doküman ve değişiklik kaydı uygulaması büyük bir lansmandan ziyade güvenilir iterasyonla ilgilidir. Hafif bir test paketi, temel gözlemlenebilirlik ve tekrarlanabilir bir dağıtım yolu, gece yarısı geri dönüşlerinden sizi kurtarır.

Pratik bir test planı

Güven kırılmasına yol açan konulara odaklanın: yanlış içerik, hatalı izinler ve yayınlama hataları.

• Birim testleri: ayrıştırma/doğrulama (Markdown render kuralları, link kontrolü, frontmatter doğrulaması, versiyon kuralları).\
• API testleri: kritik uç noktalar (doküman oluştur/düzenle, sürüm notu yayımla, arama indeksleme, izin kontrolleri).\
• Ana UI akışları: giriş, düzenle → önizle, inceleme isteği, onay → yayımla ve genel sayfanın güncellendiğini doğrulama gibi kısa uçtan uca senaryolar.

Uçtan uca test kümesini kısa ve stabil tutun; kenar durumları birim/API seviyesinde kapsayın.

Kullanışlı gözlemlenebilirlik

Başlangıç için üç sinyalle başlayın ve gerektiğinde genişletin:

• Hata takibi (frontend + backend) ve ani artışlar için uyarılar\
• Yapılandırılmış loglar: istek kimliği, kullanıcı kimliği (güvenliyse) ve içerik kimlikleri (doc/changelog id) içersin\
• Temel performans metrikleri: halka açık sayfalar için yanıt süresi yüzdeleri, editör autosave gecikmesi, arama sorgu zamanlaması

Ayrıca izin reddi ve yayın olaylarını loglayın—bunlar “Neden göremiyorum?” raporlarını çözmede çok değerlidir.

Dağıtım ve CI

İşletebileceğiniz en basit dağıtımı seçin.

• Managed platform genellikle en hızlısıdır (yerleşik TLS, ölçekleme, health check'ler).\
• Kümeniz varsa container kullanım mantıklı olabilir.

Basit bir CI hattı: testleri çalıştır, lint, varlıkları derle, kontrollü adımda migration çalıştır, sonra deploy et. Küçük ekiplerde production için manuel onay kapısı ekleyin.

Zamana ilk dağıtımı azaltmak istiyorsanız, Koder.ai dağıtım ve barındırmayı iş akışının parçası olarak halledebilir ve hazır olduğunuzda üretilen kaynak kodu dışa aktarmanıza izin verir.

Yedekleme, kurtarma ve bakım

Hem veritabanı hem dosya depolama (yüklemeler, dışa aktarılan varlıklar) için periyodik yedekleme yapın ve kurtarmayı üç ayda bir prova edin.

Bakımı periyodik bir kontrol listesiyle yapın: eski taslakları temizle, kırık linkleri tespit et, eski versiyonları arşivle/deprecate et, aramayı yeniden indeksle, kullanıcı geri bildirimlerini toplayıp editör ve iş akışı iyileştirmelerini önceliklendirin.