Հիշատակվում է որպես կոդ

1) Ճարտարապետական սկզբունքները

1. Ճշմարտության միակ աղբյուրը։ Փաստաթղթերը, սխեմաները, դիագրամները, API-ի ճշգրտումները, գլոսարիան - VCS-ում կոդի մոտ։

2. Որակի ավտոմատ ստուգում։ Լինդերները, ուղղագրությունը, հղումների ստուգումը, կոդավորման օրինակները։

3. Հավաքումը որպես արտեֆակտ։ Դոկ-կայքը, PDF/ebook, «ներկառուցված հուշումներ», մետրոպոլիտենի pline-ի մի մասը։

4. Տարբերակումը և ճանապարհը։ Դուկը ղեկավարում է նույն PR-ը, որը փոխում է համակարգի վարքագիծը։ ADR-ն կապված է համայնքներին։

5. Դերերի հասանելիությունը։ Հանրային/ներքին, Runbook "և on-call-ի տակ, API-spects ինտեգրատորների համար։

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)

Արտեֆակտները

RBC-ն որոշումների քննարկումն է նախքան ներդրումը։

ADR-ն գրված ճարտարապետական լուծում է (ենթատեքստը բացատրում է այլընտրանքի այլընտրանքային հետևանքները)։

Runbook/Playbook-ը տուրիստական և վիրահատության հրահանգներ է։

How-To/FAQ-ը վերջնական քայլերի խնդիր է, որոնք համապատասխանում են արդյունքի ստուգմանը։

API-speks-ը OpenAPI/AsyncAPI/Delo-ն է որպես RPK և բժիշկների աղբյուրը։

Դիագրամները որպես կոդ Mermaid/PlantUML/Graphviz/C4։

3) Ոճը և ստանդարտները

Մեկ առաջնորդություն ոճով (տոն, տերմինոլոգիա, վերնագրերի ձևանմուշներ, օրինակներ)։

Գլոսարիան կանոնական տերմիններով (EN/RU), ալիասներ, որոնք արգելված են ձևակերպումներով։

Համարակալումը և հղումները 'անընդհատ խարիսխ, քրոսոս հանրաքվեներ ADR/RSA/կոդ։

YAML-frontmatter-ում մետատվողները

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-ը մեծ պլատֆորմների մոդուլային բաղադրիչ է։

Mkdocs-ի օրինակ։ yml (հատված)

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 (հաջորդականության օրինակ)

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

PlantUML (C4 բեռնարկղեր)

@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-ը/տերմինաբանություն/ton-ն է։

Spellcheck-ը օրֆոգրաֆիա է (RU/EN բառարաններ)։

Linkcheck-ը արտաքին/ներքին հղումներ, խարիսխ է։

Doctest/Examples-ը կոդի բեկորների կատարումն է, CLI/API տարբերակների համաժամեցումը։

Schematest - OpenAPI/AsyncAPI/JSON Schema/Delo։

GitHub Actions (հատված)։

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

Doctest օրինակ (Python)

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/www.ipets/calc։ py`.

7) Գործընթացներ ՝ RFC/ADR/ակնարկներ և SLA հնացած

RMS flow: Ռուսական չեռնովիկի նախաձեռնողը բացատրում է, որ լուծումը հաստատվում է ռետրոյի հետպատերազմյան պլանով։

ADR flow: Կարճ ժամանակ մենք գրանցում ենք ընտրությունը + հղում RFC/փորձարկումների վրա։

Review ընթացակարգերը 'աղբյուրը' "CODEOWNERS '+' doc-owners։ yaml`.

SLA հնացած. կրիտիկական հոդվածները ունեն «lim _ review» և ալերտ 'N օրվա ընթացքում։

IslandADR (abr.)։

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/< wwww.ale>։

Ստեյբլ-ID-ը վերնագրերի/բեկորների համար։

Ստուգումներ 'քայլ' missing-keys ", ալտերտեր ռասինխրոնիզացիայի վրա։

Սթիլի լոկալներ 'տեղական գլոսարիա, անընդունելի կաղնիներ, UI-ի տեղական լեզվով կոդի օրինակներ։

9) Ինտեգրումը սննդի հետ

Ներկառուցված (in-ap docs) 'MDX բաղադրիչներ, կոնտեքստային հուշումներ։

Հաղորդագրությունների տարբերակումը 'թեգեր/ճյուղեր' docs/vX։ Y ', medector տարբերակների կայքը։

Հատվածների արտադրությունը 'OpenAPI/AsyncAPI, GraphQL SDL, CLI' ---help "։

Changelog որպես կոդ 'ավտոմատ PR (feat/fix/dos/breaking)։

10) Մետրիկի և փաստաթղթերի դիտարկումը

Docs SLO 'հավաքման/հրապարակման ժամանակը, կայքի ապտայմը, փաստաթղթի հայտնվելը PR-ից հետո։

Արտեֆակտների ծածկումը 'ADR-ի հետ ծառայությունների մասնաբաժինը, էնդպոինտների մասնաբաժինը, օրինակ, Runbook-ի մասնաբաժինը «առողջության ստուգման» հետ։

Օգտագործողի մետրերը 'որոնման հարցումներ առանց պատասխանների, դիտման խորությունը, CTR ներկառուցված հուշումներ։

Որակը 'ոսպնյակների/1000 տողերի սխալները, «բիթային հղումները», հնացած հոդվածների մասը։

11) Անվտանգությունն ու գաղտնիությունը

Գաղտնիքները և PD-ն արգելված են ռեպոյի մեջ։ ոսպնյակներ գաղտնի և դիմակավորում։

Մուտք ներքին կայքին SSO-ի միջոցով։ հանրային բաժինները բաժանված են։

Էքսպորտի կանոնները 'PDP/արխիվներ առանց ներքին հղումների, գաղտնի փաստաթղթերի համար հիբրիդային նշաններ։

Բուլգարիան սկրինշոտներ 'ավտոմատ անանունացում (ռոք-տվյալներ/բլուր)։

12) Patterns

Docs in PR. Ցանկացած փոփոխություն, որը ազդում է վարքագծի վրա, ներառում է բժիշկների նորարարություն նույն PR-ում։

Ձևանմուշները որպես պայմանագիր։ / endpoint/dazaset-ի ստեղծումը գեներատորի միջոցով է, որը տեղադրում է ռուսական բժիշկները։

Դիագրամները որպես կոդ։ Ցանկացած նկարը խմբագրված հեղինակն է, SVG/PNG հավաքածուը CI-ում։

Docs Preview. Բոտայի մեկնաբանությունը, վկայակոչելով PR-ի համար կայքի կանխատեսումը։

Դոկ-ոսպնյակներ կոդում։ Հայտնագործությունները աղբյուրներում («@ doc: adr/0007»), որոնք փոխանցվում են կայքում։

13) Anti-patterna

Wiki/Notion-ում առանց կոդով տարբերակների տեղադրվում է ռասինխրոնիզացիա։

Սկրինշոտները առանց ելքերի ապացուցում են ինքնաբերաբար թարմացնելու անհնարինությունը։

«Գաղտնի» գիտությունը բանավոր զրույցներում և մասնավոր ֆայլերում։

Առանց օրինակների և ինվարանտների արտադրողները անօգուտ էջեր են պարունակում։

Սեփականատերերի բացակայությունը և «lance _ review» -ը հնացած են։

Ձեռքի հավաքումը և հրատարակությունը բացատրվում են բժիշկների լուռ և հազվագյուտ թողարկմամբ։

14) Ավտոմատացման օրինակներ

Ռուսական API-ի գեներացիան սպեկներից

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/

Բոտը կանխատեսում է (մեկնաբանություն PR)

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-speks (OpenAPI/AsyncAPI/Delo) valididions և rending կայքում։

6. Կազմակերպված է docs-medview-ի համար PR-ի համար և մեքենայի հրատարակումը merge-ով։

7. Գոյություն ունի SLA հնացած (lom _ review) և էջերի «սեփականատերերը»։

8. Պիտակներ ՝ ծածկույթ, ոսպնյակների սխալներ, բիթանոց հղումներ, որոնման «զրոյական» հարցումներ։

9. Անվտանգության քաղաքականությունը 'գաղտնիքները արգելված են, SSO, էքսպորտային նշաններ/էքսպորտներ։

10. Տեղայնացումը կառավարվում է ճյուղերով և ստուգվում է անցքերի վրա։

Եզրակացություն

Docs-as-Code-ը վերածում է փաստաթղթեր «հետֆակտից» զարգացման աշխատանքային արտեֆակտին 'տարբերակված, թեստավորված և առաքված։ Այդ մոտեցման դեպքում գիտելիքը ապրում է կոդի կողքին, փոփոխությունները թափանցիկ են, իսկ օգտագործողները և ինժեներները ստանում են համապատասխան հրահանգներ, սխեմաներ և օրինակներ, երբ դրանք անհրաժեշտ են։ Սա նվազեցնում է վիրահատական ռիսկերը, արագացնում է ուռուցքաբանությունը և բարելավում լուծումների որակը ամբողջ պլատֆորմում։