Hujjatlar kod sifatida

1) Arxitektura prinsiplari

1. Haqiqatning yagona manbai. Hujjatlar, sxemalar, diagrammalar, API spetsifikatsiyalari, glossariy - kod yonidagi VCSda.
2. Sifatni avtomatik tekshirish. Linterlar, imlo, havolalarni tekshirish, kod namunalarini doctest.
3. Artefakt sifatida yig’ish. Doc-sayt, PDF/ebook, «ichki maslahatlar» - reliz payplaynning bir qismidir.
4. Version va traskorlik. Dock tizimning xatti-harakatlarini oʻzgartiradigan PRni boshqaradi; ADR kommitlarga bogʻlangan.
5. Rollar bo’yicha foydalanish imkoniyati. Ommaviy/ichki, Runbook’va on-call ostida, integratorlar uchun API-speklar.
6. Minimal qo’l ishlari. Sarlavhalar, sxemalar, bog’liqlik grafalari, kod parchalari manbalardan ishlab chiqariladi.

2) Hujjatlar turlari va repo tuzilmasi

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 - amalga oshirishdan oldin qarorlarni muhokama qilish.
• ADR - oʻrnatilgan arxitektura yechimi (kontekst → yechim → oqibatlar → muqobil).
• Runbook/Playbook - hodisalar va operatsiyalar uchun bosqichma-bosqich koʻrsatmalar.
• How-To/FAQ - vazifa → qadamlar → natijani tekshirish.
• API-speklar - OpenAPI/AsyncAPI/Proto SDK va doklarni ishlab chiqarish manbai sifatida.
• Diagrammalar kod sifatida Mermaid/PlantUML/Graphviz/C4.

3) Uslub va standartlar

Uslub bo’yicha yagona qo’llanma (ton, terminologiya, sarlavha shablonlari, misollar).
Kanonik atamalar (EN/RU), aliaslar, taqiqlangan iboralarga ega bo’lgan glossariy.
Raqamlash va havolalar: doimiy langarlar, ADR/RFC/kod orasidagi kross-referensiyalar.

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

4) Yig’ish va nashr etish

• MkDocs (Material) - oddiy, qulay, yaxshi navigatsiya va qidiruv.
• Docusaurus - hujjatlar versiyasi va docs + blog; MDX komponentlari.
• Antora - yirik platformalar uchun modulli hujjatlar.

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 va sxemalar kod sifatida

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 saytga renderlanadi; ulardan SDK/mijozlar/misollar hosil qilinadi.

6) Sifat: linterlar va hujjatlar testlari

• markdownlint - Markdown formatlash qoidalari.
• Vale - uslub/terminologiya/ton.
• Spellcheck - imlo (RU/EN lugʻatlari).
• Linkcheck - tashqi/ichki havolalar, langarlar.
• Doctest/Examples - kod parchalarini bajarish, CLI/API versiyalarini sinxronlashtirish.
• Schematest - OpenAPI/AsyncAPI/JSON Schema/Proto validatsiyasi.

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’ni ishga tushiradi. py`.

7) Jarayonlar: RFC/ADR/sharhlar va eskirish SLA

RFC flow: tashabbuskor → loyiha → muhokama → yechim → reja → implementatsiya → post-faktum retro.
ADR flow: Tanlash + RFC/tajriba havolasi.
Review-protseduralar: manba -’CODEOWNERS’+’doc-owners. yaml`.
SLA eskirishi uchun: tanqidiy maqolalar’last _ review’ga ega bo’ladi va N kundan keyin g’azablangan alertga ega bo’ladi.

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) Mahalliylashtirish (i18n) va ko’p tilli

Lokalizatsiya strategiyasi: boshlang’ich til (EN yoki RU) → tarjimasi’18n/< locale>’.
Kalit va kontekst: sarlavhalar/parchalar uchun «stabl-ID» ni saqlash.
Tekshirish:’missing-keys’qadami, sinxronlashtirish uchun alertlar.
Lokal uslublar: lokal glossariyalar, nomaqbul kalkalar, lokal tildagi kod namunalari.

9) Mahsulot bilan integratsiya qilish

Ichki maʼlumot (in-app docs): MDX komponentlari, kontekstli maslahatlar.
Relizlar boʻyicha versiya: teglar/filiallar’docs/vX. Y’, selector versiyali sayt.
Seksiyalarning avtogeneratsiyasi: OpenAPI/AsyncAPI, GraphQL SDL, CLI’-help’dan.
Changelog kod sifatida: PR (feat/fix/docs/breaking) belgilari bo’yicha avtomatik ishlab chiqarish.

10) Hujjatlarning metrikasi va kuzatilishi

Docs SLO: yig’ish/nashr etish vaqti, saytning aptaymi, PRdan keyin hujjatning paydo bo’lish vaqti.
Artefaktlar bilan qoplash: ADR bilan xizmatlar ulushi, misollar bilan endpointlar ulushi, «salomatlikni tekshirish» bilan Runbook’lar ulushi.
Foydalanuvchi metrikasi: javobsiz qidiruv soʻrovlari, koʻrish chuqurligi, oʻrnatilgan maslahatlarning CTR.
Sifati: linter xatolari/1000 satr, «sindirilgan havolalar», eskirgan maqolalar ulushi.

11) Xavfsizlik va maxfiylik

Repoda sirlar va PD taqiqlangan; sirlar va yashirinish uchun linterlar.
SSO orqali ichki saytga kirish; ommaviy bo’limlar ajratilgan.
Eksport qoidalari: PDF/ichki havolalarsiz arxivlar, maxfiy hujjatlar uchun suv belgilari.
Skrinshotlar sanitariyasi: avtomatik anonimlashtirish (moq-ma’lumotlar/blur).

12) Patternlar

Docs in PR. Xulq-atvorga ta’sir qiluvchi har qanday o’zgarish o’sha PRdagi doklarni yangilashni o’z ichiga oladi.
Shablonlar shartnoma sifatida. Servis/endpint/dataset yaratish - doklarni tayyorlaydigan generator orqali.
Diagrammalar kod sifatida. Har qanday rasm - tahrirlanadigan manba, SVG/PNG ni CI ga yigʻish.
Docs Preview. PR uchun saytni oldindan koʻrib chiqishga havola qilingan bot sharhi.
Doc-linki kodda. Saytga renderlanadigan manbadagi izohlar (’@doc: adr/0007’).

13) Anti-patternlar

Hujjatlar wiki/Notion’da versiyasiz, kod yonida → rassinxronizatsiya.
Manbasiz skrinshotlar → avtomatik ravishda yangilab boʻlmaydi.
Og’zaki chatlar va shaxsiy fayllardagi «maxfiy» bilimlar.
Misol va invariantsiz generiklar → foydasiz sahifalar.
Egasining yoʻqligi va’last _ review’→ eskirgan koʻchki.
Qo’lda yig’ish va nashr etish → Docklarning zaif va noyob relizi.

14) Avtomatlashtirish namunalari

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) Arxitektorning chek-varaqasi

1. Dockning yagona repozitoriyasi kod yonida va aniq tuzilishi bormi?
2. Namunalar (RFC/ADR/Runbook/How-To) va lugʻat tavsiflanganmi?
3. Linterlar (markdownlint, Vale), spellcheck, linkcheck va doctest yoqilganmi?
4. Diagrammalar va sxemalar - kod sifatida, CIda yigʻish?
5. API-speklar (OpenAPI/AsyncAPI/Proto) saytga kiritiladimi?
6. PR uchun docs-preview va merge boʻyicha avto-nashr tashkil etilganmi?
7. Sahifalarning eskirishi (last_review) va «egalari» uchun SLA bormi?
8. Metriklar: qamrov, linter xatolari, singan havolalar, qidiruv «nol» soʻrovlari?
9. Xavfsizlik siyosati: sirlar taqiqlangan, SSO, suv belgilari/eksport?
10. Lokalizatsiya shoxlar bilan boshqariladi va o’tkazib yuboriladimi?

Xulosa

Docs-as-Code hujjatlarni «postfaktum eslatmalaridan» ishlab chiqish ishchi artefaktiga aylantiradi: versiya qilinadigan, sinovdan o’tkaziladigan va yetkazib beriladigan. Bunday yondashuv bilan bilim kod yonida yashaydi, o’zgarishlar shaffof bo’ladi, foydalanuvchilar va muhandislar esa zarur bo’lganda dolzarb ko’rsatmalar, sxemalar va misollar oladi. Bu operatsion xavflarni kamaytiradi, onbordingni tezlashtiradi va butun platforma boʻylab yechimlar sifatini yaxshilaydi.