დოკუმენტაცია კოდის სახით

1) არქიტექტურული პრინციპები

1. ჭეშმარიტების ერთი წყარო. დოკუმენტები, სქემები, დიაგრამები, API სპეციფიკაციები, ტერმინები - VCS- ში კოდის გვერდით.
2. ხარისხის ავტომატური შემოწმება. ლინტერები, მართლწერა, ბმულების შემოწმება, კოდის მაგალითები.
3. შეკრება, როგორც არტეფაქტი. DOK საიტი, PDF/ebook, „ჩაშენებული მინიშნებები“ არის გამოშვებული რულონის ნაწილი.
4. ვერსია და ტრეკირება. დოქი მართავს იმავე 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 + ბლოგი; MDX კომპონენტები.
• ანტორა არის მოდულური დოკუმენტაცია დიდი პლატფორმებისთვის.

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.
• ვალე - სტილი/ტერმინოლოგია/ტონი.
• 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 ნაკადი: მოკლედ ჩაწერეთ არჩევანი + ბმული RFC/ექსპერიმენტებზე.
მიმოხილვის პროცედურები: წყარო - 'CODEOWNERS' + 'doc-owners. yaml`.
SLA მოძველებისთვის: კრიტიკულ სტატიებს აქვთ 'last _ Review' და Alert on 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>'.
გასაღებები და კონტექსტი: შეინახეთ „stable-ID“ სათაურები/ფრაგმენტები.
შემოწმებები: ნაბიჯი 'missing-keys', ალერტები რასინქრონიზაციისთვის.
ლოკალების სტილები: ადგილობრივი ტერმინალები, მიუღებელი ნიმუშები, კოდის მაგალითები ადგილობრივ UI ენაზე.

9) პროდუქტთან ინტეგრაცია

ჩაშენებული სერტიფიკატი (app docs): MDX კომპონენტები, კონტექსტური რჩევები.
გამოშვების ვერსია: ჭდეები/ფილიალები 'docs/vX. Y ', საიტი შერჩევითი ვერსიებიდან.
სექციების ავტომატური წარმოება: OpenAPI/AsyncAPI- დან, GraphQL SDL, CLI '-help' - დან.
Changelog, როგორც კოდი: ავტომატური წარმოება PR ეტიკეტებზე (feat/fix/docs/breaking).

10) მეტრიკა და დოკუმენტაციის დაკვირვება

Docs SLO: შეკრების/გამოქვეყნების დრო, საიტის აფთიაქი, დოკუმენტის გამოჩენის დრო PR- ის შემდეგ.
არტეფაქტების დაფარვა: სერვისების წილი ADR- სთან, მაგალითებით ენდოინების წილი, Runbook- ის წილი „ჯანმრთელობის შემოწმებით“.
მომხმარებლის მეტრიკა: საძიებო მოთხოვნები პასუხის გარეშე, ნახვის სიღრმე, CTR ჩაშენებული რჩევები.
ხარისხი: ლინტერის შეცდომები/1000 სტრიქონი, „გატეხილი ბმულები“, მოძველებული სტატიების წილი.

11) უსაფრთხოება და კონფიდენციალურობა

საიდუმლოებები და PD აკრძალულია რეპოში; საიდუმლოებები და შენიღბვა.
შიდა საიტზე წვდომა SSO- ს საშუალებით; საზოგადოებრივი სექციები გამოყოფილია.
ექსპორტის წესები: PDF/არქივები შიდა კავშირების გარეშე, კონფიდენციალური დოკუმენტების წყლის ნიშნები.
ეკრანის კადრები: ავტომატური ანონიმიზაცია (მაქს-მონაცემები/ბლური).

12) პატერნები

Docs in PR. ნებისმიერი ცვლილება, რომელიც გავლენას ახდენს ქცევაზე, მოიცავს დოქტების განახლებას იმავე PR- ში.
შაბლონები კონტრაქტს ჰგავს. სერვისის/endpoint/dataset- ის შექმნა - გენერატორის მეშვეობით, რომელიც დოქების ბლანკებს აყენებს.
დიაგრამები კოდია. ნებისმიერი ნიმუში არის რედაქტირებული წყარო, ასამბლეა SVG/PNG CI- ში.
Docs Preview. ბოტის კომენტარი PR- სთვის საიტის წინასწარი შემოწმების საფუძველზე.
Doc-links კოდი. წყაროებში განთავსებული ვიდეოები ('@ 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. ჩართულია linters (markdownlint, Vale), spellcheck, linkcheck და doctest?
4. დიაგრამები და სქემები - როგორც კოდი, ასამბლეა CI- ში?
5. API სპეკები (OpenAPI/AsyncAPI/Proto) დალაგებულია და განახლებულია საიტზე?
6. მოეწყო docs-preview PR- სთვის და მანქანის გამოცემა მერჯზე?
7. არსებობს SLA მოძველებისთვის (last _ review) და გვერდების „მფლობელები“?
8. მეტრიკა: საფარი, ლინტერის შეცდომები, გატეხილი ბმულები, საძიებო „ნულოვანი“ მოთხოვნები?
9. უსაფრთხოების პოლიტიკოსები: საიდუმლოებები აკრძალულია, SSO, წყლის ნიშნები/ექსპორტი?
10. ლოკალიზაცია კონტროლდება ფილიალებით და შემოწმებულია?

დასკვნა

Docs-as-Code დოკუმენტაციას „ნოტების შემდგომი ფაქტიდან“ გადააქცევს განვითარების სამუშაო არტეფაქტად: ვერსია, ტესტირება და მიწოდებული. ამ მიდგომით, ცოდნა ცხოვრობს კოდის გვერდით, ცვლილებები გამჭვირვალეა, ხოლო მომხმარებლები და ინჟინრები იღებენ შესაბამის მითითებებს, სქემებსა და მაგალითებს, როდესაც საჭიროა. ეს ამცირებს ოპერაციულ რისკებს, აჩქარებს ონბორდინგს და აუმჯობესებს გადაწყვეტილებების ხარისხს მთელ პლატფორმაზე.