Kod hökmünde resminamalar

1) Binagärlik ýörelgeleri

1. Hakykatyň ýeke-täk çeşmesi. Resminamalar, shemalar, diagrammalar, API aýratynlyklary, sözlük - koduň gapdalyndaky VCS-de.
2. Awtomatiki hil barlagy. Linterler, orfografiýa, baglanyşyklary barlamak, kod mysallarynyň doctest.
3. Artefakt hökmünde ýygnamak. Doc-sahypa, PDF/ebook, "gurlan maslahatlar" - goýberilen paýlaýjynyň bir bölegi.
4. Wersiýalaşdyrmak we yzarlamak. Dok ulgamyň özüni alyp barşyny üýtgedýän şol bir PR dolandyrýar; ADR komitlere birikdirildi.
5. Rollar boýunça elýeterlilik. Jemgyýetçilik/içerki, Runbook 'we on-call, integratorlar üçin API bölekleri.
6. Iň az el işi. Mazmuny, shemalary, garaşlylyk grafalaryny, kod böleklerini döretmek - çeşmelerden.

2) Resminamalaryň görnüşleri we repo gurluşy

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 - durmuşa geçirmezden ozal çözgütleri ara alyp maslahatlaşmak.
• ADR - kesgitlenen binagärlik çözgüdi (kontekst → çözgüt → netijeler → alternatiwalar).
• Runbook/Playbook - wakalar we amallar üçin ädimme-ädim görkezmeler.
• How-To/FAQ - wezipe → ädimler → netijäni barlamak.
• API-spekleri - OpenAPI/AsyncAPI/Proto SDK we Dock döretmek çeşmesi hökmünde.
• Diagrammalar kod hökmünde Mermaid/PlantUML/Graphviz/C4.

3) Stil we standartlar

Stil boýunça bitewi gollanma (äheň, terminologiýa, sözbaşy şablonlary, mysallar).
Kanoniki adalgalar (EN/RU), aliaslar, gadagan formulalar bilen sözlük.
Belgiler we baglanyşyklar: ADR/RFC/kod arasyndaky hemişelik labyrlar, kross-salgylanmalar.

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

4) Ýygnamak we çap etmek

• MkDocs (Material) - ýönekeý, amatly, gowy nawigasiýa we gözleg.
• Docusaurus - resminamalaryň wersiýasy we docs + blog; MDX komponentleri.
• Antora - uly platformalar üçin modully resminamalar.

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) Diagrammalar we shemalar kod hökmünde

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 saýta render edilýär; olardan SDK/müşderiler/mysallar emele gelýär.

6) Hil: linterler we resminamalar synaglary

• markdownlint - Markdown formatlamak düzgünleri.
• Vale - stil/terminologiýa/äheň.
• Spellcheck - orfografiýa (RU/EN sözlükleri).
• Linkcheck - daşarky/içerki baglanyşyklar, labyrlar.
• Doctest/Examples - kod böleklerini ýerine ýetirmek, CLI/API wersiýalaryny sinhronlamak.
• Schematest - OpenAPI/AsyncAPI/JSON Schema/Proto.

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. py`.

7) Amallar: RFC/ADR/synlar we SLA köne

RFC akymy: inisiator → taslama → çekişme → çözgüt → meýilnama → implementasiýa → post-faktum retro.
ADR akymy: saýlamagy gysgaça ýazýarys + RFC/synaglary baglanyşyk.
Gözden geçirme amallary: çeşme - 'CODEOWNERS' + 'doc-owners. yaml`.
SLA könelişmek üçin: möhüm makalalarda 'last _ review' bar we N günden soň rewýuda alert bar.

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) Lokalizasiýa (i18n) we köp dillilik

Lokalizasiýa strategiýasy: asyl dil (EN ýa-da RU) → terjime '18n/< locale>'.
Açarlar we kontekst: sözbaşylar/bölekler üçin "stabl-ID" saklamak.
Barlamak: ädim 'missing-keys', synchronization üçin alertler.
Lokallaryň stilleri: lokal sözbaşylar, kabul ederliksiz kalkalar, lokal dildäki kod mysallary UI.

9) Önüm bilen integrasiýa

Içerki kömek (in-app docs): MDX komponentleri, kontekstli maslahatlar.
Çykyş wersiýasy: bellikler/şahalar 'docs/vX. Y ', saýt selector wersiýalary bilen.
Bölümleriň awtogenerasiýasy: OpenAPI/AsyncAPI, GraphQL SDL, CLI '-help' -den.
Changelog kod hökmünde: PR bellikleri boýunça awtomatiki nesil (feat/fix/docs/breaking).

10) Dokumentleriň ölçegleri we syn edilmegi

Docs SLO: ýygnalan/çap edilen wagty, sahypanyň aptaimi, PR-den soň resminamanyň peýda bolan wagty.
Artefaktlar bilen örtülmegi: ADR bilen hyzmatlaryň paýy, mysallar bilen endpointleriň paýy, "saglyk barlagy" bilen Runbook 'laryň paýy.
Ulanyjy metrikleri: jogapsyz gözleg soraglary, gözlemek çuňlugy, içerki maslahatlaryň CTR-leri.
Hil: linterleriň ýalňyşlyklary/1000 setirler, "döwülen baglanyşyklar", köne makalalaryň paýy.

11) Howpsuzlyk we gizlinlik

Repoda syrlar we PD gadagan edilýär; syr we gizlemek üçin linterler.
SSO arkaly içerki sahypa girmek; jemgyýetçilik bölümleri aýrylýar.
Eksport düzgünleri: Içerki baglanyşyksyz PDF/arhiwler, gizlin resminamalar üçin suw bellikleri.
Skrinshotlaryň arassaçylygy: awtomatiki adynyň aýdylmazlygy (mok-data/blur).

12) Patternler

Docs in PR. Özüni alyp barşyna täsir edýän islendik üýtgeşme şol bir PR-daky doklaryň täzelenmegini öz içine alýar.
Şablonlar şertnama hökmünde. Hyzmat/endpoint/dataset döretmek - doklaryň taýýarlyklaryny goýýan generator arkaly.
Diagrammalar kod hökmünde. Islendik çyzgy - redaktirlenip bilinjek çeşme, CI-de SVG/PNG ýygnamak.
Docs Preview. PR üçin saýtyň deslapky gözden geçirilişine salgylanmak bilen bot teswirleri.
Koddaky doklar. Sahypany görkezýän düşündirişler ('@doc: adr/0007').

13) Anti-patternler

Wiki/Notion-daky resminamalar kodyň gapdalynda wersiýasyz → rasinhronizasiýa.
Çeşmesiz skrinshotlar → awtomatiki täzelenip bilmezlik.
Dilden söhbetdeşliklerde we şahsy faýllarda "gizlin" bilimler.
Mysalsyz we üýtgeşikliksiz generikler → peýdasyz sahypalar.
Eýeleriniň ýoklugy we 'last _ review' → könelişen gar.
El bilen ýygnamak we neşir etmek → doklaryň döwük we seýrek çykmagy.

14) Awtomatlaşdyrmagyň mysallary

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) Arhitektoryň çek-sanawy

1. Koduň gapdalyndaky doklaryň ýeke-täk repozitory we düşnükli gurluşy barmy?
2. Şablonlar (RFC/ADR/Runbook/How-To) we sözlük beýan edilýärmi?
3. Linterler (markdownlint, Vale), spellcheck, linkcheck we doctest goşuldymy?
4. Diagrammalar we shemalar - kod ýaly, CI-de ýygnamak?
5. API spekleri (OpenAPI/AsyncAPI/Proto) tassyklanýar we sahypa render edilýär?
6. PR üçin docs-preview we merge boýunça awto-neşir gurnaldymy?
7. Sahypalaryň köne (last_review) we "eýeleri" üçin SLA barmy?
8. Metrikler: örtük, linter ýalňyşlyklary, döwülen baglanyşyklar, gözleg "nol" soraglary?
9. Howpsuzlyk syýasaty: syrlar gadagan, SSO, suw bellikleri/eksport?
10. Lokalizasiýa şahalar bilen dolandyrylýar we geçişler üçin barlanýar?

Netije

Docs-as-Code resminamany "faktumdan soňky belliklerden" işläp düzmegiň iş artefaktyna öwürýär: wersiýalanýan, synagdan geçirilýän we getirilýän. Bu çemeleşme bilen bilim koduň ýanynda ýaşaýar, üýtgeşmeler aç-açan bolýar we ulanyjylar we inersenerler zerur bolanda degişli görkezmeleri, shemalary we mysallary alýarlar. Bu bolsa iş töwekgelçiligini peseldýär, onbording işini çaltlaşdyrýar we tutuş platforma boýunça çözgütleriň hilini ýokarlandyrýar.