الوثائق كرمز

1) المبادئ المعمارية

1. مصدر واحد للحقيقة. المستندات والرسوم البيانية والرسوم البيانية ومواصفات واجهة برمجة التطبيقات ومسرد المصطلحات - في VCS بجوار الكود.
2. فحص الجودة التلقائي. البطانات، الهجاء، فحص الروابط، أمثلة الرموز الأكثر وضوحًا.
3. التجميع كقطعة أثرية. موقع الإرساء، PDF/ebook، «تلميحات مدمجة» - جزء من خط أنابيب الإصدار.
4. الإصدار وإمكانية التتبع. يحكم Doc نفس العلاقات العامة التي تغير سلوك النظام ؛ إن تقييمات النتائج الإنمائية مقيدة بالالتزام.
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 - تعليمات خطوة بخطوة للحوادث والعمليات.
• كيفية/الأسئلة الشائعة - مهام → خطوات → التحقق من النتيجة.
• مواصفات واجهة برمجة التطبيقات - OpenAPI/AsyncAPI/Proto كمصدر لجيل وأرصفة SDK.
• الرسوم البيانية كرمز - Mermaid/PlantUML/Graphviz/C4.

3) الأسلوب والمعايير

دليل النمط الفردي (النغمة، المصطلحات، قوالب العنوان، الأمثلة).
مسرد بمصطلحات قانونية (EN/RU)، أسماء مستعارة، صيغ محظورة.
الترقيم والمراجع: المراسي الدائمة، المراجع بين ADR/RFC/code.

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

يتم تسليم OpenAPI/AsyncAPI إلى الموقع ؛ وينتج منها عملاء/عملاء/أمثلة.

6) الجودة: البطانات واختبارات التوثيق

• Markdownlint - قواعد تنسيق Markdown.
• Vale - style/terminology/tone.
• Spellcheck - spelling (RU/EN dictionaries).
• Linkcheck - روابط خارجية/داخلية، مراسي.
• Doctest/Examples - تنفيذ مقتطفات الرمز، تزامن إصدارات CLI/API.
• Schematest - OpenAPI/AsyncAPI/JSON Schema/Proto validation.

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 و SLAs للتقادم

RFC flow: initiative draft copy discussion decision plan implementation retro posto.
تدفق ADR: إصلاح الاختيار + الإشارة إلى RFC/التجارب لفترة وجيزة.
إجراءات المراجعة: المصدر - «CODEOWNERs' +» أصحاب المستندات. yaml'.
SLA للتقادم: المقالات النقدية لديها «آخر _ مراجعة» وتنبيه للمراجعة في أيام 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>'.
المفاتيح والسياق: تخزين «معرف مستقر» للرؤوس/الشظايا.
الشيكات: خطوة «مفاتيح مفقودة»، تنبيهات لعدم التزامن.
أنماط الموقع: مسارد محلية، ورقة تتبع غير صالحة، أمثلة على الكود بلغة واجهة المستخدم المحلية.

9) تكامل المنتج

مساعدة مدمجة (مستندات داخل التطبيق): مكونات MDX، تلميحات السياق.
الإصدار عن طريق الإصدار: مستندات/فروع/vX. Y '، موقع مع إصدارات محددة.
التوليد التلقائي للأقسام: من OpenAPI/AsyncAPI و GraphQL SDL و CLI '--help'.
Changelog كرمز: التوليد التلقائي بواسطة ملصقات العلاقات العامة (الفذ/الإصلاح/المستندات/الكسر).

10) مقاييس الوثائق وإمكانية رصدها

Docs SLO: بناء/نشر الوقت، وقت تشغيل الموقع، وقت ظهور المستند بعد العلاقات العامة.
تغطية القطع الأثرية: حصة الخدمات مع ADRs، حصة نقاط النهاية مع الأمثلة، حصة Runbooks مع «الفحوصات الصحية».
مقاييس المستخدم: عمليات بحث بدون إجابة، عمق المشاهدة، CTR للمطالبات المدمجة.
الجودة: أخطاء البطانة/1000 سطر، «روابط مكسورة»، نسبة المقالات القديمة.

11) الأمن والخصوصية

الأسرار والشرطة محظورة في إعادة الشراء ؛ بطانات للأسرار والإخفاء.
الوصول إلى الموقع الداخلي عن طريق أجهزة الأمن الخاصة ؛ الأجزاء العامة منفصلة.
قواعد التصدير: PDF/archives without internal links, watermarks for contributional documents.
لقطة شاشة الصرف الصحي: إخفاء الهوية تلقائيًا (بيانات mok/ضبابية).

12) الأنماط

مستندات في العلاقات العامة. يتضمن أي تغيير يؤثر على السلوك تحديث الأرصفة في نفس العلاقات العامة.
النماذج كعقد. إنشاء خدمة/نقطة نهاية/مجموعة بيانات - من خلال مولد يضع فراغات الرصيف.
الرسوم البيانية كرمز. أي صورة - مصدر قابل للتحرير، تجمع SVG/PNG في CI.
معاينة المستندات. تعليق الروبوت مع رابط لمعاينة الموقع للعلاقات العامة.
رسو الروابط في الرمز. الشروح في المصادر ('@ doc: adr/0007') التي تقدم إلى الموقع.

13) الأنماط المضادة

التوثيق في ويكي/الفكرة بدون إصدارات بجوار الكود → خارج المزامنة.
لقطات الشاشة بدون مصادر → عدم القدرة على التحديث تلقائيًا.
المعرفة «السرية» في الدردشات الشفوية والملفات الخاصة.
الأدوية العامة بدون أمثلة والثابتة → صفحات عديمة الفائدة.
نقص المالكين و «المراجعة الأخيرة» → سيل من التقادم.
→ التجميع والنشر اليدويان إصدارًا هشًا ونادرًا للأرصفة.

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. هل تم التحقق من صحة مواصفات واجهة برمجة التطبيقات (OpenAPI/AsyncAPI/Proto) وتقديمها إلى الموقع ؟

6. معاينة مستندات منظمة للعلاقات العامة والنشر التلقائي عن طريق الدمج ؟

7. هل هناك اتحادات SLA (last_review) و «مالكو» الصفحات ؟

8. المقاييس: التغطية، أخطاء البطانة، الروابط المكسورة، استفسارات البحث «صفر» ؟

9. السياسات الأمنية: الأسرار المحظورة، SSO، العلامات المائية/الصادرات ؟

10. يتم التحكم في التوطين من قبل الفروع والتحقق من الإغفالات ؟

خامسا - الاستنتاج

يحول Docs-as-Code الوثائق من «ملاحظات ما بعد الحقائق» إلى قطعة أثرية عاملة للتطوير: تم تحريرها واختبارها وتسليمها. مع هذا النهج، تعيش المعرفة بجوار الكود، والتغييرات شفافة، ويتلقى المستخدمون والمهندسون تعليمات ومخططات وأمثلة محدثة عند الحاجة. هذا يقلل من المخاطر التشغيلية ويسرع من الصعود إلى الطائرة ويحسن جودة الحلول عبر النظام الأساسي.