Документ катары код

1) Архитектуралык принциптер

1. чындыктын бир булагы. Документтер, схемалар, диаграммалар, API спецификациялары, глоссарий - коддун жанындагы VCSде.
2. Автоматтык сапатын текшерүү. Линтерлер, орфография, шилтемелерди текшерүү, коддун мисалдарын doctest.
3. артефакт катары чогултуу. Doc-сайт, PDF/ebook, "орнотулган кеңештер" - релиздик пайплайндын бир бөлүгү.
4. Версиялоо жана трассалануу. Doc системанын жүрүм-турумун өзгөртөт ошол эле PR башкарат; ADR коммиттерге байланган.
5. Ролдор боюнча жеткиликтүүлүк. Коомдук/ички, Runbook 'жана on-call астында, интеграторлор үчүн 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-SPECTS - OpenAPI/AsyncAPI/Proto SDK жана док муунунун булагы катары.
• Диаграммалар код катары 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 (Material) - жөнөкөй, ыңгайлуу, жакшы багыттоо жана издөө.
• Docusaurus - документтердин жана docs + blog версиясы; 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

OpenAPI/AsyncAPI сайтта рендерлик; алардын SDK/кардарлар/мисалдар түзүлөт.

6) Сапаты: Линтерс жана документтерди сыноо

• markdownlint - Markdown форматтоо эрежелери.
• Vale - стили/терминология/тон.
• Spellcheck - орфография (RU/EN сөздүктөрү).
• Linkcheck - тышкы/ички шилтемелер, казыктар.
• Doctest/Examples - коддун үзүндүлөрүн аткаруу, CLI/API версияларын синхрондоштуруу.
• 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) жараяндар: RFC/ADR/Reviews жана эскирүү SLA

RFC агымы: демилгечиси → долбоор → талкуу → чечим → план → ишке ашыруу → пост-чындык ретро.
ADR агымы: кыскача тандоо чечүү + RFC шилтеме/эксперименттер.
Review-процедуралар: булак - 'CODEOWNERS' + 'doc-owners. yaml`.
SLA эскирүү үчүн: сын макалалар N күндөн кийин ревю боюнча 'last _ review' жана alert бар.

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" сактоо.
Текшерүүлөр: кадам 'missing-keys', расинхронизация үчүн алерталар.
Локалдык стилдер: локалдык глоссарийлер, алгылыксыз калькилер, локалдык UI тилиндеги коддун мисалдары.

9) продукт менен бириктирүү

Орнотулган жардам (in-app docs): MDX компоненттери, контексттик кеңештер.
Чыгаруу версиясы: tags/бутактар 'docs/vX. Y ', selector нускалары менен сайт.
Секциялардын автогенерациясы: OpenAPI/AsyncAPI, GraphQL SDL, CLI '-help'.
Код катары Changelog: автоматтык PR (feat/fix/docs/breaking).

10) Метрика жана документтердин байкоо

Docs SLO: чогултуу/жарыялоо убактысы, сайт, PR кийин документ пайда болгон убакыт.
Артефакттар менен камтуу: ADR менен кызматтардын үлүшү, мисалдар менен эндпоинттердин үлүшү, "ден соолукту текшерүү" менен Runbook 'тардын үлүшү.
Колдонуучу метриктер: жоопсуз издөө сурамдары, көрүү тереңдиги, CTR орнотулган кеңештер.
Сапаты: linters ката/1000 сап, "сынган шилтемелер", эскирген макалалардын үлүшү.

11) Коопсуздук жана купуялык

Жашыруун жана PD репо тыюу салынат; сырлар жана жашыруу үчүн линтерлер.
SSO аркылуу ички сайтка кирүү; коомдук бөлүмдөр бөлүнгөн.
Экспорттун эрежелери: PDF/ички шилтемелери жок архивдер, жашыруун документтер үчүн суу белгилери.
Скриншоттордун санитариясы: автоматтык анонимдештирүү (мок-маалыматтар/blur).

12) Үлгүлөр

Docs in PR. Жүрүм-турумга таасир этүүчү ар кандай өзгөртүү ошол эле PRдеги докторду жаңылоону камтыйт.
Шаблондор келишим катары. кызмат/EndPoint/Dataset түзүү - док даярдоо коюп генератор аркылуу.
Диаграммалар код катары. Ар бир чийме - редактордук булак, CI SVG/PNG чогултуу.
Docs Preview. Комментарий бот PR үчүн сайтты алдын ала көрүү шилтеме менен.
Код боюнча док-линктер. Баштапкы булактардагы аннотациялар ('@doc: adr/0007'), алар сайтка тартылат.

13) Анти-үлгүлөрү

Wiki/Notion документтери коддун жанында эч кандай версиясы жок → синхрондоштуруу.
Скриншоттор жок баштапкы → автоматтык түрдө жаңыртуу мүмкүн эмес.
оозеки чаттар жана жеке документтерде "жашыруун" билим.
Generics эч кандай мисалдар жана инварианттар → пайдасыз барактар.
ээлеринин жоктугу жана '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. Linters кирет (markdownlint, Vale), spellcheck, linkcheck жана doctest?
4. Диаграммалар жана схемалар - код сыяктуу, CI чогултуу?
5. API-Спек (OpenAPI/AsyncAPI/Proto) тастыкталып, сайтта рендерлик?
6. Уюштурулган docs-preview үчүн PR жана auto-жарыялоо боюнча merge?
7. эскирген SLA бар (last_review) жана "ээлери" барактар?
8. Метрика: жабуу, Линтер каталар, сынган шилтемелер, издөө "нөл" суроо?
9. Коопсуздук саясаты: сырлар тыюу салынган, SSO, суу белгилери/экспорт?
10. Локализация бутактар ​ ​ тарабынан башкарылат жана пропуск үчүн текшерилет?

Корутунду

Docs-as-Code документтерди "постфактум жазууларынан" иштеп чыгуунун жумушчу артефактына айландырат: версиялануучу, сыналуучу жана жеткирилүүчү. Мындай ыкма менен билим коддун жанында жашайт, өзгөрүүлөр ачык-айкын, ал эми колдонуучулар жана инженерлер керектүү учурда актуалдуу көрсөтмөлөрдү, схемаларды жана мисалдарды алышат. Бул операциялык тобокелдиктерди азайтат, байланышты тездетет жана платформа боюнча чечимдердин сапатын жакшыртат.