Ҳуҷҷатгузорӣ ҳамчун рамз

1) Принсипҳои меъморӣ

1. Манбаи ягонаи ҳақиқат. Ҳуҷҷатҳо, диаграммаҳо, диаграммаҳо, мушаххасоти API, луғат - дар VCS дар паҳлӯи рамз.
2. Санҷиши худкори сифат. Линтерҳо, имло, санҷиши пайванд, намунаҳои рамзи doctest.
3. Маҷлис ҳамчун артефакт. Сомонаи docking, PDF/ebook, "маслиҳатҳои дарунсохт" - қисми лӯлаи озодкунӣ.
4. Версия ва пайгирӣ. Doc ҳамон PR-ро идора мекунад, ки рафтори системаро тағйир медиҳад; ADR-ҳо ӯҳдадоранд.
5. Дастрасӣ аз рӯи нақш. Ҷамъият/дохилӣ, Runbook 'ва ҳангоми занг, хусусиятҳои API барои интеграторҳо.
6. Ҳадди ақали дастӣ. Тавлиди ҷадвалҳои мазмунҳо, диаграммаҳо, графикҳои вобастагӣ, порчаҳои рамзӣ - аз манбаъҳо.

2) Намудҳои ҳуҷҷат ва сохтори репо

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 - Пеш аз татбиқ ҳалли онҳоро муҳокима кунед.
• ADR - ҳалли собитшудаи меъморӣ (контекст → ҳалли → оқибатҳои § алтернатива).
• Runbook/Playbook - дастурҳои зина ба зина барои ҳодисаҳо ва амалиёт.
• How-To/FAQ - вазифа → қадамҳо → натиҷаро тафтиш кунед.
• Хусусиятҳои API - Open
• Диаграммаҳо ҳамчун рамз - Mermaid/PlantUML/Graphviz/C4.

3) Услуб ва стандартҳо

Дастури услуби ягона (оҳанг, истилоҳот, қолабҳои унвон, намунаҳо).
Луғат бо истилоҳҳои каноникӣ (EN/RU), тахаллусҳо, формулаҳои манъшуда.
Рақамгузорӣ ва истинодҳо: лангарҳои доимӣ, истинодҳои байни ADR/RFC/код.

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

4) Маҷлис ва нашр

• MKdocs (Мавод) - содда, қулай, паймоиш ва ҷустуҷӯи хуб.
• Docusaurus - нусхаи ҳуҷҷатгузорӣ ва ҳуҷҷатҳо + блог; Ҷузъҳои MDX.
• Antora - ҳуҷҷатгузории модулӣ барои платформаҳои калон.

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) Диаграммаҳо ва диаграммаҳо ҳамчун рамз

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

Open-API/AsyncAPI ба сайт пешниҳод карда мешавад; SDK/мизоҷон/намунаҳо аз онҳо тавлид мешаванд.

6) Сифат: санҷишҳои линтерҳо ва ҳуҷҷатгузорӣ

• markdownlint - Қоидаҳои форматкунии Markdown.
• Vale - услуб/истилоҳот/оҳанг.
• Spellcheck - имло (луғатҳои RU/EN).
• Linkcheck - пайвандҳои беруна/дохилӣ, лангарҳо.
• Doctest/Мисолҳо - иҷрои порчаҳои код, ҳамоҳангсозии версияҳои CLI/API.
• Schematest - Тасдиқи Schema/Proto Open

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) Равандҳо: RFC/ADR/Reviews ва SLA-ҳо барои кӯҳна

Ҷараёни RFC: ташаббускор → лоиҳаи нусхабардорӣ → муҳокима → қарор → нақша → татбиқ → retro post facto.
Ҷараёни ADR: мухтасар интихоб + истинод ба RFC/таҷрибаҳоро ислоҳ кунед.
Тартиби бознигарӣ: манбаъ - 'CODEOWNERS' + 'соҳибони ҳуҷҷатҳо. ямл '.
SLA барои кӯҳна: мақолаҳои интиқодӣ 'last _ review' доранд ва барои баррасӣ дар рӯзҳои N ҳушдор медиҳанд.

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) Маҳаллисозӣ (i18n) ва бисёрзабонӣ

Стратегияи маҳаллисозӣ: забони манбаъ (EN ё RU) → тарҷума аз ҷониби филиалҳои 'i18n/< locale>'.
Калидҳо ва контекст: барои сарлавҳаҳо/фрагментҳо "устувор-ID" -ро нигоҳ доред.
Санҷишҳо: қадами 'калидҳои нопурра', огоҳиҳо барои desynchronization.
Услубҳои маҳаллӣ: луғатҳои маҳаллӣ, коғазҳои беэътибор, намунаҳои код дар забони маҳаллии UI.

9) Интегратсияи маҳсулот

Кӯмаки дарунсохт (ҳуҷҷатҳои дохили барнома): ҷузъҳои MDX, маслиҳатҳои контекстӣ.
Нусхабардорӣ аз рӯи нашр: барчаспҳо/ҳуҷҷатҳои филиалҳо/VX. Y ', сайт бо версияҳои селекторӣ.

Тавлиди худкори бахшҳо: аз Open

Changelog ҳамчун рамз: тавлиди худкор аз рӯи тамғакоғазҳои PR (feat/fix/docs/break).

10) Нишондиҳандаҳо ва мушоҳидаҳои ҳуҷҷатгузорӣ

Ҳуҷҷатҳои SLO: вақт, вақти корӣ, вақти пайдоиши ҳуҷҷат пас аз PR.
Фарогирии Artifact: ҳиссаи хидматҳо бо ADR, мубодилаи нуқтаҳои ниҳоӣ бо мисолҳо, ҳиссаи Runbook бо "санҷиши саломатӣ".
Нишондиҳандаҳои корбар: ҷустуҷӯҳои беҷавоб, умқи дидан, CTR-и дархостҳои дарунсохт.
Сифат: хатогиҳои линтер/1000 хат, "пайвандҳои шикаста", таносуби мақолаҳои кӯҳна.

11) Амният ва махфият

Дар репоҳо асрори ва PD манъ аст; линтерҳо барои асрори ва ниқоб.
Дастрасӣ ба сайти дохилӣ тавассути SSO; бахшҳои ҷамъиятӣ ҷудо шуданд.
Қоидаҳои содирот: PDF/бойгонӣ бидуни истиноди дохилӣ, нишонаҳои обӣ барои ҳуҷҷатҳои махфӣ.
Санитарияи скриншот: беном кардани автоматӣ (mok data/blur).

12) Намунаҳо

Ҳуҷҷатҳо дар PR. Ҳама гуна тағироте, ки ба рафтор таъсир мерасонад, нав кардани докҳоро дар ҳамон PR дар бар мегирад.
Шаблонҳо ҳамчун шартнома. Таъсиси хидмат/нуқтаи ниҳоӣ/маҷмӯа - тавассути генераторе, ки бланкаҳои бандро мегузорад.
Диаграммаҳо ҳамчун рамз. Ҳама гуна расм - манбаи таҳриршаванда, маҷлиси SVG/PNG дар CI.
Пешнамоиши ҳуҷҷатҳо. Шарҳи Bot бо истинод ба пешнамоиши сайт барои PR.
Пайвандҳои docking дар рамз. Эзоҳҳо дар манбаъҳо ('@ doc: adr/0007'), ки ба сайт пешниҳод карда мешаванд.

13) Анти-намунаҳо

Ҳуҷҷатгузорӣ дар wiki/Notion бе версияҳои оянда дар назди рамз → берун аз синхронизатсия.
Скриншотҳо бе манбаъҳо → имконнопазирии навсозӣ ба таври худкор.
Дониши "махфӣ" дар чатҳои даҳонӣ ва файлҳои хусусӣ.
Генерикҳо бе намунаҳо ва ғайривариантҳо → саҳифаҳои бефоида.
Набудани соҳибон ва 'last _ review' → тармаи кӯҳна.
Монтаж ва нашри дастӣ → нашри нозук ва нодири докҳо.

14) Намунаҳои автоматизатсия

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) Рӯйхати назорати меъморон

1. Дар паҳлӯи рамз ва сохтори возеҳ як анбори ягонаи докҳо мавҷуд аст?
2. Шаблонҳо (RFC/ADR/Runbook/How-To) ва луғати тасвиршуда?
3. Линтерҳо (markdownlint, Vale), имло, linkcheck ва doctest?
4. Диаграммаҳо ва диаграммаҳо - ба монанди рамз, васлкунӣ дар CI?

5. Оё хусусиятҳои API (Open

6. Пешнамоиши муташаккилонаи PR ва худкор нашр тавассути якҷоя?
7. Оё SLA-ҳои пиронсол (last_review) ва "соҳибони" саҳифаҳо ҳастанд?
8. Нишондиҳандаҳо: фарогирӣ, хатогиҳои линтер, истинодҳои шикаста, дархостҳои "сифр" -ро ҷустуҷӯ кунед?
9. Сиёсати амният: сирри манъшуда, SSO, нишонаҳо/содирот?
10. Маҳаллисозӣ аз ҷониби филиалҳо назорат карда мешавад ва камбудиҳоро тафтиш мекунад?

Хулоса

Docs-as-Code ҳуҷҷатҳоро аз "ёддоштҳои пас аз факт" ба артефакти кории рушд табдил медиҳад: санҷидашуда, санҷидашуда ва таҳвилшуда. Бо ин равиш, дониш дар паҳлӯи рамз зиндагӣ мекунад, тағирот шаффоф аст ва корбарон ва муҳандисон ҳангоми зарурат дастурҳо, диаграммаҳо ва намунаҳои муосирро мегиранд. Ин хатарҳои амалиётиро коҳиш медиҳад, дар киштӣ суръат мегирад ва сифати қарорҳоро дар платформа беҳтар мекунад.