مستندات به عنوان کد

1) اصول معماری

1. تنها یک منبع حقیقت اسناد، نمودارها، نمودارها، مشخصات API، واژه نامه - در VCS در کنار کد.
2. بررسی کیفیت اتوماتیک. Linters، املا، چک کردن لینک، نمونه های کد doctest.
3. مجمع به عنوان مصنوعی. سایت Docking، PDF/ebook، «ساخته شده در نکات» - بخشی از خط لوله انتشار.
4. نسخه و ردیابی. Doc همان PR را تنظیم می کند که رفتار سیستم را تغییر می دهد. ADR ها متعهد هستند.
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 - دستورالعمل های گام به گام برای حوادث و عملیات.
• 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 (مواد) - ساده، راحت، ناوبری خوب و جستجو.
• 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 به سایت ارائه می شود ؛ SDK/مشتریان/نمونه ها از آنها تولید می شود.

6) کیفیت: خطوط و آزمون مستندات

• markdownlint - قوانین قالب بندی Markdown.
• Vale - سبک/اصطلاحات/تن.
• املای املایی (لغت نامه های RU/EN).
• Linkcheck - لینک های خارجی/داخلی، لنگرها.
• Doctest/Examples - اجرای قطعه کد، همگام سازی نسخه های CLI/API.
• Schematest - OpenAPI/AsyncAPI/JSON Schema/اعتبار سنجی پروتو.

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

python -m doctest docs/snippets/calc را اجرا می کند. خیلی خب.

7) فرآیندها: RFC/ADR/بررسی ها و SLA ها برای منسوخ شدن

RFC flow: initiator → draft copy → discussion → decision → plan → implementation → retro post facto.
جریان ADR: به طور خلاصه انتخاب + مرجع RFC/آزمایش را ثابت کنید.
روش های بررسی: منبع - 'CODEOLDERS' + 'doc-صاحبان. «يامل».
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>'.
کلید ها و زمینه: ذخیره «stable-ID» برای هدر/قطعات.
چک: مرحله «کلید های از دست رفته»، هشدار برای desynchronization.
سبک های محلی: واژه نامه های محلی، مقاله ردیابی نامعتبر، نمونه هایی از کد در زبان UI محلی.

9) ادغام محصول

راهنمای داخلی (اسناد درون برنامه): اجزای MDX، نکات زمینه.
نسخه با انتشار: برچسب ها/شاخه ها docs/vX. Y، یک سایت با نسخه های انتخابگر.
تولید خودکار بخش ها: از OpenAPI/AsyncAPI، GraphQL SDL، CLI «- help».
Changelog به عنوان کد: تولید خودکار توسط برچسب های PR (شاهکار/تعمیر/اسناد/شکستن).

10) معیارها و قابلیت مشاهده مستندات

اسناد SLO: ساخت/انتشار زمان، آپ تایم سایت، زمان ظاهر سند پس از PR.
پوشش Artifact: سهم خدمات با ADR، سهم نقاط پایانی با نمونه ها، سهم Runbooks با «چک های بهداشتی».
معیارهای کاربر: جستجوهای بدون پاسخ، عمق مشاهده، CTR از پیشنهادات داخلی.
کیفیت: خطاهای خطی/1000 خط، «لینک های شکسته»، نسبت مقالات منسوخ شده است.

11) امنیت و حریم خصوصی

اسرار و PD در مخازن ممنوع است. برای اسرار و ماسک زدن.

دسترسی به سایت داخلی از طریق SSO ؛ بخش های عمومی جدا شده

قوانین صادرات: PDF/آرشیو بدون لینک داخلی، علامت برای اسناد محرمانه.
بهداشت تصویر: ناشناس سازی خودکار (mok data/blur).

12) الگوها

اسناد در روابط عمومی هر تغییری که بر رفتار تاثیر می گذارد شامل به روز رسانی اسکله ها در همان PR است.
قالب ها به عنوان قرارداد ایجاد یک سرویس/نقطه پایانی/مجموعه داده - از طریق یک ژنراتور که جاهای خالی را قرار می دهد.
نمودار به عنوان کد هر تصویر - منبع قابل ویرایش، مونتاژ SVG/PNG در CI.
پیشنمایش اسناد. نظر ربات با لینک به پیش نمایش سایت برای روابط عمومی.
لینک های متصل به کد حاشیه نویسی در منابع ('doc: adr/0007') که به سایت ارائه می شود.

13) ضد الگوهای

مستندات در ویکی/مفهوم بدون نسخهها در کنار کد → خارج از همگامسازی.
تصاویر بدون منبع → عدم توانایی به روز رسانی به صورت خودکار.
دانش «راز» در چت های شفاهی و فایل های خصوصی.

Generics بدون مثال و صفحات غیر قابل استفاده

فقدان صاحبان و «آخرین بررسی» → بهمن منسوخ.
مونتاژ و انتشار دستی → انتشار شکننده و نادر از اسکله.

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. پیش نمایش اسناد سازمان یافته برای PR و انتشار خودکار توسط ادغام ؟

7. آیا SLA های پیری (last_review) و «صاحبان» صفحات وجود دارد ؟

8. معیارها: پوشش، خطاهای خطی، لینک های شکسته، جستجو «صفر» نمایش داده شد ؟

9. سیاست های امنیتی: اسرار ممنوع، SSO، علامت های سفید/صادرات ؟

10. محلی سازی توسط شاخه ها کنترل می شود و برای نادیده گرفتن بررسی می شود ؟

نتیجه گیری

Docs-as-Code مستندات را از «یادداشت های پس از واقعیت» به یک کار مصنوعی توسعه تبدیل می کند: نسخه، تست شده و تحویل داده شده است. با این رویکرد، دانش در کنار کد زندگی می کند، تغییرات شفاف هستند و کاربران و مهندسان دستورالعمل ها، نمودارها و نمونه های به روز را در صورت نیاز دریافت می کنند. این خطرات عملیاتی را کاهش می دهد، سرعت در حال بارگذاری و کیفیت راه حل ها را در سراسر پلت فرم بهبود می بخشد.