Dokümantasyon yazım ve review rehberi

Önce doğru audience

Dokümanı, dosyanın konusuna değil okuyucunun yapacağı işe göre yerleştirin:

Alan	Okuyucu ve içerik	İçermemesi gerekenler
user	Ürünü kullanan kişinin görevi ve gözleyebildiği davranış	İç implementasyon ve planlanmış davranış
developer	Kod, schema, API, pipeline, test ve operasyon sözleşmesi	Kanıtsız sistem iddiası
project	Karar, provenance, kalite, release ve yürütme kaydı	Günlük kullanıcı yardımı
generated	Migration, RPC, CLI veya release kaynağından türetilen referans	Elle düzeltilmiş generated çıktı

Bir değişiklik birden fazla alanı etkiliyorsa her alan kendi canonical artifact’ında güncellenir. Aynı açıklamayı kopyalamak yerine ortak source of truth’a bağ verin.

Doğruluk ve durum

• Mevcut davranışı şimdiki zamanla, planı açıkça gelecek çalışma olarak yazın.
• Yayınlanmamış kullanıcı davranışı draft kalır; verified yalnız ilgili doğrulama çalıştıktan sonra kullanılır.
• Komut, route, environment adı, schema ve stable ID’yi kaynaktaki exact yazımıyla verin. Secret veya gerçek credential örneği kullanmayın.
• Canonical metin, veri veya provenance iddiasını tahminden üretmeyin; kaynak locator’ı ve gerekli evidence’ı gösterin.
• doc_id, locale ve redirect kuralları için doküman kimliği rehberini izleyin.

Yazım ve yapı

• Başlık ve ilk paragraf sayfanın gerçek görevini doğrudan söylesin.
• Kısa, etkin ve somut cümleler kullanın; aynı kavram için aynı terimi koruyun.
• Önkoşulları işlem adımlarından önce, doğrulamayı işlemin hemen ardından verin.
• Adımları ancak sıra önemliyse numaralandırın. Seçenek ve koşulları düz liste veya tabloyla ayırın.
• Hata durumunda gözlenen belirtiyi, muhtemel nedeni ve güvenli çözümü birlikte yazın. Legacy kaynağı değiştirmeyi çözüm veya rollback olarak önermeyin.
• Başlık seviyelerini atlamayın. Bağ metni hedefi açıklasın; buraya tıklayın gibi bağlamdan bağımsız ifadeler kullanmayın.

Komut, kod ve görsel

• Public giriş noktası varsa iç komut yerine root make hedefini gösterin.
• Çalıştırılabilir komutları kod bloğuna alın; placeholder’ı açık ve sahte değerle belirtin. Çıktıyı ancak okuyucu karar vermek için ihtiyaç duyuyorsa ekleyin.
• Kod örneği minimum ama tamamlanabilir olsun; kütüphane ve davranış sürümünü applies_to veya yakın metinde sınırlandırın.
• Görselin aktardığı bilgiyi alt metinde verin. Renk, konum veya ikon tek başına anlam taşımasın; tablo başlıkları ve callout türleri açık olsun.

Çeviri ve generated içerik

Çeviri canonical Türkçe sayfayla aynı doc_id ve audience’ı taşır. Çevirmen anlamı, domain terimlerini ve komutları korur; eksik Türkçe karşılığı başka dilde varmış gibi sunmaz. Dil akıcılığı review’u, kaynak davranışının teknik review’unun yerine geçmez.

Generated sayfa elle düzenlenmez. Generator, kaynak ve provenance değiştirilir; çıktı yeniden üretilir ve diff doğrulanır. Generated içeriğin sahibi generator sözleşmesinden ve kaynağın güncelliğinden sorumludur; içeriğin semantik doğruluğunu ait olduğu audience’ın reviewer’ı ayrıca inceler.

Ownership ve review

Her doküman değişikliğinde dokümantasyon maintainer’ı yapı, metadata, link ve audience sınırını inceler. İçerik doğruluğu ayrıca şu role aittir:

Değişiklik	Gerekli içerik review’u	Review sorusu
user	User/domain reviewer	Akış gerçekten çalışıyor, anlaşılır ve erişilebilir mi?
developer	İlgili teknik owner	Kod, schema, API veya operasyon sözleşmesi exact mı?
project	Project/governance owner	Karar, provenance ve evidence birbirini destekliyor mu?
generated	Generator/source owner ve ilgili audience reviewer	Provenance, üretilebilirlik ve içerik anlamı birlikte doğru mu?
Çeviri	Canonical audience reviewer ve language reviewer	Anlam ve dil birlikte korunuyor mu?

Test, lint, build ve link checker sonuçlarını lead veya CI bir kez evidence’a bağlar. İçerik reviewer’ı sırf bu komutları tekrar çalıştırıp sonuç aktaran bir proxy değildir; audience, anlam, domain ve risk üzerinde bağımsız karar verir. Yüksek riskli işte bağımsızlık veya birden fazla onay gerekiyorsa bunu ilgili packet ve repository rule ayrıca zorunlu kılar. Tek kişinin bugün birden fazla rolü üstlenmesi kendiliğinden bağımsız quorum sayılmaz.

İki ownership kimliği

Frontmatter owners, documentation-maintainers gibi kalıcı işlevsel rol kimliğidir; URL veya GitHub hesabı değildir. .github/CODEOWNERS ise GitHub’ın değişen path için review isteği yönelteceği mevcut hesap veya e-postadır. Bir hesap değiştiğinde doc_id veya işlevsel owner rolü değişmez.

CODEOWNERS tek başına onay, semantik doğruluk veya bağımsızlık kanıtı değildir. Public remote henüz yapılandırılmadığı için required review ve branch protection bu repoda uygulanmış kabul edilmez; remote açıldığında kurallar ayrıca etkinleştirilmeli ve owner kimliği doğrulanmalıdır.

Katkı akışı

1. Audience’ı ve etkilenen canonical dokümanı belirleyin.
2. Davranışla dokümanı aynı değişiklikte güncelleyin; generated çıktıyı kaynağı üzerinden üretin.
3. PR’da docs-impact, gerekçe ve değişen artifact bağlarını doldurun.
4. Yukarıdaki matristen içerik reviewer’ını isteyin ve çalışan doğrulama komutlarını kaydedin.
5. Review bulgularını yeni commit ile kapatın; uygulanmayan davranışı verified olarak yayımlamayın.