Kod kimi sənədləşdirmə

1) Memarlıq prinsipləri

1. Həqiqətin vahid mənbəyi. Sənədlər, sxemlər, diaqramlar, API spesifikasiyaları, sözlük - kodun yanında VCS-də.
2. Avtomatik keyfiyyət yoxlama. Linterlər, orfoqrafiya, linklərin yoxlanılması, kod nümunələrinin doctest.
3. Bir artefakt kimi montaj. Dock saytı, PDF/ebook, «daxili ipuçları» - buraxılış payplaynın bir hissəsidir.
4. Version və izləmə qabiliyyəti. Doc sistemin davranışını dəyişdirən eyni PR-ni idarə edir; ADR kommitlərə bağlıdır.
5. Rollara görə əlçatanlıq. Public/daxili, Runbook 'və on-call altında, inteqratorlar üçün API spins.
6. Minimum əl işi. İçindəkilərin, sxemlərin, asılılıq qrafiklərinin, kod fraqmentlərinin generasiyası - mənbələrdən.

2) Sənəd növləri və repo strukturu

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 - tətbiq edilməzdən əvvəl həllərin müzakirəsi.
• ADR - sabit memarlıq həlli (kontekst → həll → nəticələri → alternativ).
• Runbook/Playbook - hadisələr və əməliyyatlar üçün addım-addım təlimat.
• How-To/FAQ - tapşırıq → addımlar → nəticənin yoxlanılması.
• API Specks - OpenAPI/AsyncAPI/Proto SDK və Dock Generation mənbəyi kimi.
• Kod kimi diaqramlar Mermaid/PlantUML/Graphviz/C4.

3) Stil və standartlar

Vahid üslub təlimatı (ton, terminologiya, başlıq şablonları, nümunələr).
Kanonik terminlər (EN/RU), aliaslar, qadağan edilmiş ifadələr olan lüğət.
Nömrələnmə və linklər: ADR/RFC/kod arasında daimi çapraz referanslar.

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

4) Montaj və nəşr

• MkDocs (Material) - sadə, rahat, yaxşı naviqasiya və axtarış.
• Docusaurus - sənədlərin və docs + blogun versiyası; MDX komponentləri.
• Antora - böyük platformalar üçün modul sənədləşmə.

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) Diaqramlar və sxemlər kimi kod

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 site render; bunlardan SDK/müştərilər/nümunələr yaradılır.

6) Keyfiyyət: linterlər və sənədləşmə testləri

• markdownlint - Markdown formatlaşdırma qaydaları.
• Vale - stil/terminologiya/ton.
• Spellcheck - orfoqrafiya (RU/EN lüğətləri).
• Linkcheck - xarici/daxili bağlantılar, çapalar.
• Doctest/Examples - kod fraqmentlərinin icrası, CLI/API versiyalarının sinxronizasiyası.
• Schematest - OpenAPI/AsyncAPI/JSON Schema/Proto validasiyası.

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 başlatır 'python -m doctest docs/snippets/calc. py`.

7) Proseslər: RFC/ADR/rəylər və köhnəlmiş SLA

RFC flow: təşəbbüskar → layihə → müzakirə → həll → plan → implementation → post-faktum retro.
ADR flow: seçimi qısaca qeyd + RFC/təcrübələrə keçid.
Review-prosedurları: mənbə - 'CODEOWNERS' + 'doc-owners. yaml`.
köhnəlmiş SLA: kritik məqalələr N gün sonra review 'last _ review' və alert 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) Lokalizasiya (i18n) və çoxdilli

Lokalizasiya strategiyası: orijinal dil (EN və ya RU) → tərcümə filialları 'i18n/< locale>'.
Açarlar və kontekst: başlıqlar/fraqmentlər üçün «sabit ID» saxlayın.
Yoxlamalar: «missing-keys» addımı, rassinxronizasiya üçün alertlər.
Lokal üslublar: lokal sözlər, qəbuledilməz qələmlər, yerli UI dilində kod nümunələri.

9) Məhsulla inteqrasiya

Daxili yardım (in-app docs): MDX komponentləri, kontekst ipuçları.
Buraxılışlar üzrə versiya: tags/filiallar 'docs/vX. Y ', selector versiyaları ilə bir sayt.
Bölmələrin avtogenerasiyası: OpenAPI/AsyncAPI, GraphQL SDL, CLI '-help'.
Changelog bir kod kimi: PR etiketlərinə görə avtomatik generasiya (feat/fix/docs/breaking).

10) Metrika və sənədlərin müşahidə edilməsi

Docs SLO: montaj/nəşr vaxtı, saytın aptaym, PR sonra sənədin görünüş vaxtı.
Artefaktlarla əhatə: ADR ilə xidmətlərin payı, nümunələrlə endpointlərin payı, «sağlamlıq yoxlaması» ilə Runbook-ların payı.
Xüsusi metriklər: cavabsız axtarış sorğuları, baxış dərinliyi, daxili ipuçları CTR.
Keyfiyyət: linter səhvləri/1000 sətir, «qırıq bağlantılar», köhnəlmiş məqalələrin payı.

11) Təhlükəsizlik və məxfilik

Repo sirləri və PD qadağan; sirləri və maskalanma linters.
SSO vasitəsilə daxili sayta giriş; ictimai bölmələr ayrılır.
İxrac qaydaları: PDF/daxili linksiz arxivlər, məxfi sənədlər üçün su işarələri.
Ekran görüntüləri: avtomatik anonimləşdirmə (mok-data/blur).

12) Nümunələr

Docs in PR. Davranışı təsir edən hər hansı bir dəyişiklik eyni PR-də dock yeniləməsini əhatə edir.
Şablonlar müqavilə kimi. Servisin/end point/datasetin yaradılması - dok boşluqlarını qoyan generator vasitəsilə.
Diaqramlar kod kimi. Hər hansı bir şəkil - redaktə edilə bilən mənbə, CI-də SVG/PNG montajı.
Docs Preview. PR üçün saytın preview link ilə bot şərh.
Doc-links kodda. Veb saytına render edilən mənbələrdə ('@doc: adr/0007') şərhlər.

13) Anti-nümunələr

Kodun yanında versiyasız wiki/Notion sənədləşdirilməsi → rassenkronizasiya.
Mənbə olmadan ekran görüntüləri → avtomatik yeniləmək mümkün deyil.
Şifahi söhbətlərdə və şəxsi fayllarda «gizli» biliklər.
Nümunələr və invariantlar olmadan Generics → yararsız səhifələr.
Sahiblərinin olmaması və 'last _ review' → köhnəlmiş uçqun.
Əl montaj və nəşr → qırıq və nadir boşaltma dokları.

14) Avtomatlaşdırma nümunələri

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) Memarın yoxlama siyahısı

1. Kod və başa düşülən quruluşun yanında tək bir dok anbarı varmı?
2. Təsvir şablonları (RFC/ADR/Runbook/How-To) və sözlük?
3. Linters (markdownlint, Vale), spellcheck, linkcheck və doctest daxil?
4. Diaqramlar və sxemlər - CI-də yığma kodu kimi?
5. API-spekulyasiyaları (OpenAPI/AsyncAPI/Proto) saytda təsdiqlənir və render olunur?
6. PR və avto nəşr merge üçün docs-preview təşkil?
7. SLA köhnəlmiş (last_review) və səhifə «sahibləri» var?
8. Metriklər: örtük, linter səhvləri, sındırılmış bağlantılar, axtarış «sıfır» sorğular?
9. Təhlükəsizlik siyasəti: sirləri qadağan, SSO, su işarələri/ixrac?
10. Lokalizasiya filiallarla idarə olunur və yoxlanılır?

Nəticə

Docs-as-Code sənədləri «postfaktum qeydlərindən» iş inkişaf artefaktına çevirir: versiya edilə bilən, sınaqdan keçirilə bilən və çatdırıla bilən. Bu yanaşma ilə bilik kodun yanında yaşayır, dəyişikliklər şəffafdır və istifadəçilər və mühəndislər lazım olduqda aktual təlimatlar, sxemlər və nümunələr alırlar. Bu əməliyyat risklərini azaldır, bağlama sürətləndirir və platforma üzrə həllərin keyfiyyətini yaxşılaşdırır.