Kod olarak dokümantasyon

1) Mimari ilkeler

1. Tek bir gerçek kaynağı. Belgeler, diyagramlar, diyagramlar, API spesifikasyonları, sözlük - kodun yanındaki VCS'de.
2. Otomatik kalite kontrolü. Linters, yazım, link checking, doctest kodu örnekleri.
3. Obje olarak montaj. Yerleştirme sitesi, PDF/e-kitap, "yerleşik ipuçları" - serbest bırakma boru hattının bir parçası.
4. Sürüm oluşturma ve izlenebilirlik. Doc, sistemin davranışını değiştiren aynı PR'yi yönetir; ADR'ler taahhütlü.
5. Role göre kullanılabilirlik. Entegratörler için Public/internal, Runbook've on-call, API özellikleri.
6. En az el yapımı. İçerik tablolarının oluşturulması, diyagramlar, bağımlılık grafikleri, kod parçaları - kaynaklardan.

2) Belge türleri ve repo yapısı

docs/
index. md architecture/
overview. md contexts/( C4, contexts, boundaries)
components/
data/
schemas/ (JSON Schema, Avro, Proto)
lineage/ (dataflow. md, dq-policies. md)
security/
threat-models/
key-management. md api/
openapi/ (OpenAPI. yaml)
asyncapi/ (.yaml)
grpc/ (.proto)
processes/
rfc/ (RFC-YYYY-XX-Title. md)
adr/ (ADR-0001-title. md)
runbooks/ (incident-.md)
playbooks/
sops/ (standard operating procedures)
product/
user-guides/
how-to/
faq/
i18n/
en/, en/, tr/# assets localization/
diagrams/ (Mermaid, PlantUML, Graphviz)
images/
_templates/ (RFC/ADR/Runbook templates)

• RFC - Uygulamadan önce çözümleri tartışın.
• ADR - sabit mimari çözüm (bağlam - çözüm - alternatifin sonuçları).
• Runbook/Playbook - olaylar ve işlemler için adım adım talimatlar.
• Nasıl Yapılır/SSS - görev - adımlar - sonucu kontrol edin.
• API özellikleri - OpenAPI/AsyncAPI/SDK üretimi ve dock kaynağı olarak Proto.
• Kod olarak diyagramlar - Mermaid/PlantUML/Graphviz/C4.

3) Stil ve standartlar

Tek stil kılavuzu (ton, terminoloji, başlık şablonları, örnekler).
Kanonik terimler (EN/RU), takma adlar, yasaklanmış formülasyonlar içeren sözlük.
Numaralandırma ve referanslar: kalıcı çapalar, ADR/RFC/kod arasında çapraz referanslar.

yaml title: "Payment Service: Overview"
owner: "payments-team"
reviewers: ["platform", "security"]
last_review: 2025-10-15 tags: ["architecture","payments","pci"]

4) Montaj ve yayın

• MkDocs (Malzeme) - basit, kullanışlı, iyi navigasyon ve arama.
• Docusaurus - dokümantasyon sürümü ve dokümanlar + blog; MDX bileşenleri.
• Antora - büyük platformlar için modüler dokümantasyon.

yaml site_name: Platform Docs theme:
name: material features: [navigation. tabs, content. code. annotate, search. suggest]
plugins:
- search
- mermaid2
- mkdocs-awesome-pages-plugin
- macros nav:
- Review: index. md
- Architecture:
- Overview: architecture/overview. md
- Data: architecture/data/index. md
- API:
- REST: api/openapi/index. md
- Events: api/asyncapi/index. md

5) Kod olarak diyagramlar ve diyagramlar

mermaid sequenceDiagram participant C as Client participant G as API Gateway participant S as Service
C->>G: POST /orders
G->>S: createOrder()
S-->>G: 201 + order_id
G-->>C: 201 Created

@startuml
!include <C4/C4_Container>
Person(user, "User")
System_Boundary(system, "Platform"){
Container(api, "API", "HTTP")
Container(db, "DB", "Postgres")
}
Rel(user, api, "Uses")
Rel(api, db, "CRUD")
@enduml

OpenAPI/AsyncAPI siteye işlenir; SDK/istemciler/örnekler bunlardan oluşturulur.

6) Kalite: astarlar ve dokümantasyon testleri

• markdownlint - Markdown biçimlendirme kuralları.
• Vale - stil/terminoloji/ton.
• Yazım denetimi - yazım denetimi (RU/EN sözlükleri).
• Linkcheck - harici/dahili bağlantılar, çapalar.
• Doctest/Examples - kod parçacıklarını çalıştırma, CLI/API sürümlerini senkronize etme.
• Schematest - OpenAPI/AsyncAPI/JSON Schema/Proto doğrulaması.

yaml name: docs-ci on: [pull_request, push]
jobs:
lint:
runs-on: ubuntu-latest steps:
- uses: actions/checkout@v4
- run: npm i -g markdownlint-cli
- run: markdownlint "docs//.md"
- run: pipx run codespell docs          true
- run: pipx run linkchecker docs/site          true build:
runs-on: ubuntu-latest steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
- run: pip install mkdocs-material mkdocs-mermaid2-plugin
- run: mkdocs build --strict preview:
if: github. event_name == 'pull_request'
runs-on: ubuntu-latest steps:
- uses: actions/checkout@v4
- run: mkdocs build
- uses: actions/upload-pages-artifact@v3

python docs/snippets/calc. py def add(a,b):
"""Returns sum of a and b.

>>> add(2,3)
5
"""
return a+b

CI 'python -m doctest docs/snippets/calc çalıştırır. py '.

7) İşlemler: Eskime için RFC/ADR/İncelemeler ve SLA'lar

RFC akışı: başlatıcı - taslak kopya - tartışma - karar - plan - uygulama - retro post facto.
ADR akışı: seçim + referansı RFC/deneylere kısaca düzeltin.
İnceleme prosedürleri: kaynak - 'CODEOWNERS' + 'doc-owners. Yaml '.
Eskime için SLA: kritik makaleler 'last _ review've N gün içinde inceleme için uyarı var.

markdown
ADR-0007: Select Event Log - Avro + Schema Registry
Date: 2025-10-31
Status: accepted
Context: the evolution of schemes without breaking consumers is required.
Solution: Avro + Schema Registry, backward compatibility.
Implications: tooling, compatibility tests, N services migration.
Alternatives: JSON Schema, Protobuf (rejected due to X/Y).

8) Yerelleştirme (i18n) ve çok dillilik

Yerelleştirme stratejisi: kaynak dil (EN veya RU) - 'i18n/< locale>' şubeleri tarafından çeviri.
Anahtarlar ve bağlam: Başlıklar/parçalar için "stable-ID" saklayın.
Denetimler: adım 'eksik-anahtarlar', eşzamansızlık için uyarılar.
Yerel stil: yerel sözlükler, geçersiz izleme kağıdı, yerel UI dilindeki kod örnekleri.

9) Ürün entegrasyonu

Yerleşik yardım (uygulama içi dokümanlar): MDX bileşenleri, bağlam ipuçları.
Serbest bırakılarak sürüm oluşturma: etiketler/dalların dokümanları/vX. Y ', seçici sürümleri olan bir site.
Bölümlerin otomatik oluşturulması: OpenAPI/AsyncAPI, GraphQL SDL, CLI '--help'.
Kod olarak Changelog: PR etiketleriyle otomatik üretim (feat/fix/docs/breaking).

10) Metrikler ve dokümantasyonun gözlemlenebilirliği

Dokümanlar SLO: oluşturma/yayınlama süresi, site çalışma süresi, PR sonrası belge görünüm zamanı.
Artifact kapsamı: ADR'lerle hizmetlerin paylaşımı, örneklerle uç noktaların paylaşımı,'sağlık kontrolleri'ile Runbook'ların paylaşımı.
Kullanıcı metrikleri: cevapsız aramalar, görüntüleme derinliği, yerleşik istemlerin TO'su.
Kalite: linter hataları/1000 satır, "kırık bağlantılar", eski makalelerin oranı.

11) Güvenlik ve gizlilik

Sırlar ve PD repolarda yasaktır; Sırlar ve maskeleme için astarlar.
SSO aracılığıyla dahili siteye erişim; Halka açık bölümler ayrıldı.
Dışa aktarma kuralları: Dahili bağlantıları olmayan PDF/arşivler, gizli belgeler için filigranlar.
Ekran görüntüsü sanitasyon: otomatik anonimleştirme (mok veri/bulanıklık).

12) Desenler

Halkla ilişkiler dokümanları. Davranışı etkileyen herhangi bir değişiklik, aynı PR'deki rıhtımların güncellenmesini içerir.
Sözleşme olarak şablonlar. Bir hizmet/uç nokta/veri setinin oluşturulması - dock boşlukları koyan bir jeneratör aracılığıyla.
Kod olarak grafikler. Herhangi bir resim - düzenlenebilir kaynak, CI'da SVG/PNG montajı.
Dokümanlar Önizlemesi. PR için site önizlemesine bağlantı içeren bot yorumu.
Koddaki bağlantı noktaları. Sitede oluşturulan kaynaklardaki ek açıklamalar ('@ doc: adr/0007').

13) Anti-desenler

Kodun yanındaki sürümler olmadan wiki/Notion'da dokümantasyon - senkronize değil.
Kaynakları olmayan ekran görüntüleri - otomatik olarak güncellenememesi.
Sözlü sohbetlerde ve özel dosyalarda "gizli" bilgi.
Örnekleri ve değişmezleri olmayan jenerikler - işe yaramaz sayfalar.
Sahiplerin eksikliği ve 'last _ review' - eskime bir çığ.
Manuel montaj ve yayın - rıhtımların kırılgan ve nadir bir şekilde serbest bırakılması.

14) Otomasyon örnekleri

bash build. sh scripts/render-openapi. sh api/openapi/.yaml > docs/api/openapi/index. md scripts/render-asyncapi. sh api/asyncapi/.yaml > docs/api/asyncapi/index. md

bash linkcheck --config. linkcheck. yml site/

yaml
- name: Deploy Preview run: mkdocs build && npx serve -s site -l 5000 &
- name: Comment with URL uses: peter-evans/create-or-update-comment@v4 with:
issue-number: ${{ github. event. pull_request. number }}
body: "Preview: http ://preview- $ {{github. run_id }}.local"

15) Mimar kontrol listesi

1. Kodun yanında tek bir rıhtım deposu ve açık bir yapı var mı?
2. Şablonlar (RFC/ADR/Runbook/How-To) ve sözlük açıklanmıştır?
3. Linters dahil (markdownlint, Vale), yazım denetimi, linkcheck ve doctest?
4. Diyagramlar ve diyagramlar - kod gibi, CI'da montaj?
5. API özellikleri (OpenAPI/AsyncAPI/Proto) doğrulandı ve siteye işlendi mi?
6. PR için düzenlenmiş dokümanlar-önizleme ve birleştirme ile otomatik yayınlama?
7. Yaşlanan SLA'lar (last_review) ve sayfaların "sahipleri" var mı?
8. Metrikler: kapsama, linter hataları, kırık bağlantılar, arama "sıfır" sorguları?
9. Güvenlik politikaları: sırlar yasaklandı, SSO, filigranlar/ihracat?
10. Lokalizasyon şubeler tarafından kontrol edilir ve eksiklikler için kontrol edilir?

Sonuç

Docs-as-Code, dokümantasyonu "post-fact notes'dan bir geliştirme eserine dönüştürür: sürüm, test edilmiş ve teslim edilmiştir. Bu yaklaşımla, bilgi kodun yanında yaşar, değişiklikler şeffaftır ve kullanıcılar ve mühendisler ihtiyaç duyulduğunda güncel talimatlar, diyagramlar ve örnekler alırlar. Bu, operasyonel riskleri azaltır, devreye almayı hızlandırır ve platformdaki çözümlerin kalitesini artırır.