ADR-0001 تمرکز مستندات فنی در Repository مستندات
وضعیت تصمیم
| فیلد | مقدار |
|---|---|
| شناسه | ADR-0001 |
| وضعیت | Accepted |
| تاریخ | 2026-08-15 |
| تصمیمگیرنده | Tech Lead |
| مالک | Tech Lead |
| جایگزینکننده | — |
| جایگزینشده از | — |
خلاصه تصمیم
تمام مستندات فنی مرجع Backend، Frontend و Mobile در documents/docs/technical-documentation/ نگهداری میشوند. Repositoryهای کد فقط README.md کوتاه برای Quick Start و AGENTS.md برای Rule اجرایی نزدیک کد دارند و به منبع مرکزی لینک میدهند.
زمینه
Runbookهای Deploy، اسناد Module و تصمیمهای Tooling در چند Repository کد پراکنده شده بودند. این وضعیت Navigation مشترک، جستوجو، Review تخصصی و تشخیص نسخه مرجع را دشوار میکرد و احتمال اختلاف دو نسخه از یک Rule را بالا میبرد.
محرکهای تصمیم
- نیاز به یک منبع حقیقت برای تیم فنی؛
- انتشار و جستوجوی همه اسناد با MkDocs؛
- کاهش تکرار میان Repositoryها؛
- الزام Front Matter، Navigation و Build سختگیرانه؛
- دسترسی همزمان Product، Engineering و Operations به Traceability.
دامنه
داخل دامنه
- Architecture، Standards، Module Docs، API Context، Tooling، ADR و Runbook؛
- Backend، Frontend وب و اپلیکیشن Mobile؛
- لینک و Rule همگامسازی Repositoryهای کد.
خارج از دامنه
- OpenAPI و Migration که همراه Build Backend هستند؛
- README Quick Start؛
AGENTS.mdهای Scopeمحور؛- Comment و Docstring لازم برای فهم کد.
گزینههای بررسیشده
گزینه A: نگهداری اسناد کنار هر Repository کد
مزیت آن نزدیکی به Change و Review همان Repository است. عیب اصلی پراکندگی Navigation، نبود Build مشترک و سختی کشف مرجع برای تیمهای دیگر است.
گزینه B: تمرکز تمام اسناد مرجع در Repository مستندات
مزیت آن Navigation و Quality Gate مشترک، جستوجوی واحد و مالکیت روشن است. هزینه آن نیاز به Change هماهنگ میان Repository کد و مستندات و امکان Drift در صورت رعایتنشدن Definition of Done است.
گزینه C: نگهداری نسخه کامل در هر دو محل
دسترسی محلی را آسان میکند، اما دو منبع حقیقت میسازد و هزینه همگامسازی و تناقض را بیشترین مقدار میکند.
ماتریس تصمیم
| معیار | وزن | گزینه A | گزینه B | گزینه C |
|---|---|---|---|---|
| یک منبع حقیقت | 5 | 3 | 5 | 1 |
| کشف و Navigation | 4 | 2 | 5 | 3 |
| نزدیکی به کد | 3 | 5 | 3 | 5 |
| هزینه نگهداری | 4 | 3 | 4 | 1 |
| Review بینتیمی | 4 | 2 | 5 | 3 |
تصمیم
گزینه B انتخاب شد. Hierarchy اصلی شامل 01-backend، 02-frontend، 03-mobile و 04-decisions است. هر حوزه میتواند Standards، Module، Tooling و Operations خود را با فایلهای کوچک و شمارهدار نگه دارد.
OpenAPI و Migration به دلیل نقش Build-time و Runtime در Backend باقی میمانند. سند فنی به آنها لینک میدهد و Schema را کپی نمیکند.
پیامدها
پیامدهای مثبت
- یک Navigation و Search برای تمام تیم؛
- Build، Front Matter و Link Check مشترک؛
- کاهش Duplicate و اختلاف Rule؛
- ADR و Runbook قابل کشف برای Product و Operations.
پیامدهای منفی
- تغییر Feature ممکن است به Pull Request هماهنگ در دو Repository نیاز داشته باشد.
- Developer بدون Checkout Repository مستندات Context کامل را ندارد.
- لینک Relative میان Repositoryها در GitHub محدود است و README باید لینک مناسب ارائه کند.
ریسک و کنترل
| ریسک | کنترل | مالک |
|---|---|---|
| Drift کد و سند | Gate اجباری AGENTS و Definition of Done | Tech Lead |
| لینک شکسته پس از Rename | Navigation Generator، Link Check و Strict Build | Documentation Owner |
| مخفیشدن Runbook هنگام Incident | لینک مستقیم از README و Index عملیات | DevOps/SRE |
| انتقال Secret به سایت Docs | Placeholder، Review امنیتی و Secret Scan | Security Reviewer |
برنامه اجرا
- تغییر نام بخش
engineeringبهtechnical-documentation؛ - انتقال Module و Runbookهای پراکنده بدون ساخت نسخه موازی؛
- افزودن Frontend و Mobile با ساختار شمارهدار؛
- اصلاح README و AGENTS Repositoryهای کد؛
- اجرای Navigation Generator، Link Check و Build سختگیرانه.
Rollback
اگر انتشار مرکزی مانع دسترسی عملیاتی شود، Git History امکان بازگردانی فایلها را دارد. بازگشت نباید نسخه موازی دائمی بسازد و قبل از آن باید علت شکست Navigation یا Access اصلاح شود.
اعتبارسنجی
| معیار | روش | آستانه |
|---|---|---|
| لینک داخلی | Link Validator و MkDocs | صفر لینک شکسته |
| Build | mkdocs build --strict |
Exit Code صفر |
| Duplicate مرجع | Search در Repositoryهای کد | بدون docs/ فنی موازی |
| کشفپذیری | Navigation سایت | دسترسی حداکثر در سه سطح |
اثر امنیتی
تمرکز سند Visibility را افزایش میدهد؛ بنابراین Credential، IP خصوصی غیرضروری، Secret، Token و داده شخصی واقعی نباید وارد سایت شوند. Runbookهای دارای Host عمومی فقط اطلاعات لازم عملیات را نگه میدارند و Private Key یا Token را هرگز ثبت نمیکنند.