Құжат код ретінде

1) Сәулет қағидаттары

1. Ақиқаттың бір көзі. Құжаттар, схемалар, диаграммалар, API ерекшеліктері, глоссарий - кодпен қатар VCS-де.
2. Автоматты түрде сапаны тексеру. Линтерлер, орфография, сілтемелерді тексеру, код мысалдарын doctest.
3. Артефакт ретінде құрастыру. Док-сайт, 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-арнайы - 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/шолулар және ескіру SLA

RFC flow: бастамашы → жоба → талқылау → шешім → жоспар → имплементация → постфактум ретро.
ADR flow: таңдауды + RFC/эксперименттерге сілтемені қысқаша белгілеңіз.
Review-процедуралар: дереккөз - 'CODEOWNERS' + 'doc-owners. yaml`.
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» сақтау.
Тексерулер: 'missing-keys' қадамы, рассинхронизацияға алерта.
Жергілікті стильдер: жергілікті глоссарийлер, жарамсыз калькалар, жергілікті UI тіліндегі код мысалдары.

9) Өніммен интеграциялау

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

10) Құжаттаманың өлшемдері мен бақылануы

Docs SLO: жинау/жариялау уақыты, сайт аптайымы, PR кейін құжаттың пайда болу уақыты.
Артефактiлермен қамту: ADR бар сервистердiң үлесi, мысалдары бар эндпоинттардың үлесi, «денсаулықты тексерумен» Runbook үлесi.
Пайдаланушы өлшемдері: жауапсыз іздеу сұраулары, қарау тереңдігі, кіріктірілген кеңестер CTR.
Сапасы: линтерлер қателері/1000 жол, «сынған сілтемелер», ескірген мақалалар үлесі.

11) Қауіпсіздік және құпиялылық

Құпиялар мен ПД репода тыйым салынған; құпияларға линтерлер және бүркемелеу.
SSO арқылы ішкі торапқа қатынау; жария бөлімдер бөлінген.
Экспорт ережелері: PDF/ішкі сілтемелері жоқ мұрағаттар, құпия құжаттар үшін су белгілері.
Скриншоттардың санитариясы: автоматты түрде анонимдеу (мок-деректер/blur).

12) Паттерндер

Docs in PR. Мінез-құлыққа әсер ететін кез келген өзгеріс сол PR доктарын жаңартуды қамтиды.
Үлгілер келісім-шарт ретінде. Сервис/эндпоинт/датасет құру - доктар дайындамаларын қоятын генератор арқылы.
Диаграммалар код ретінде. Кез келген сурет - өңделетін бастапқы, CI-ге SVG/PNG құрастыру.
Docs Preview. PR үшін сайтты алдын ала қарауға сілтеме жасайтын боттың түсініктемесі.
Кодтағы док-линкалар. Торапқа ренделетін бастапқы аңдатпалар ('@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), spellcheck, linkcheck және doctest?
4. Диаграммалар мен схемалар - код сияқты, CI-ге құрастыру?
5. API-ерекшеліктер (OpenAPI/AsyncAPI/Proto) сайтта валидацияланады және рендіріледі ме?
6. PR үшін docs-preview және merge бойынша авто-жарияланым ұйымдастырылды ма?
7. Ескіру (last_review) және «бет иелері» үшін SLA бар ма?
8. Метриктер: жабу, линтерлердің қателері, сынған сілтемелер, «нөлдік» іздеу сұраулары?
9. Қауіпсіздік саясаты: құпия, SSO, су белгілері/экспорт?
10. Оқшаулау бұтақтармен басқарылады және рұқсатнамаға тексеріледі ме?

Қорытынды

Docs-as-Code құжаттаманы «постфактум жазбаларынан» әзірлеудің жұмыс артефактісіне айналдырады: нұсқаланатын, тестіленетін және жеткізілетін. Мұндай тәсілмен білім кодпен қатар өмір сүреді, өзгерістер ашық, ал пайдаланушылар мен инженерлер қажет болған жағдайда өзекті нұсқаулықтар, схемалар мен мысалдар алады. Бұл операциялық тәуекелдерді төмендетеді, онбордингті жеделдетеді және бүкіл платформа бойынша шешімдердің сапасын жақсартады.