‏یه پوشه، یه تاپیک: مستندات رو کنار کد نگه دار

نویسنده می‌گه تو هر شرکتی که کار کرده، مستندات همون مشکل همیشگی رو داشته: صفحه‌های Confluence کم‌کم از کدی که توصیفش می‌کنن عقب می‌افتن. یه بار برای اینکه بفهمه یه پرداخت چطوری تو سیستم جابه‌جا می‌شه، چهار صفحه پیدا کرده بود. دوتاش با هم تناقض داشتن، یکیش دربارهٔ سرویسی بود که پاک شده بود و هیچ‌کدوم صاحب نداشتن. دلیلش ساده‌ست: نمی‌شه یه صفحهٔ ویکی رو تو همون pull request کد عوض کرد. ایجنت‌های هوش مصنوعی هم اصلاً به Confluence دسترسی نداشتن.

راه‌حلشون یه قرارداد سه‌خطی تو یه README بود. هر ریپو مستنداتش رو به صورت Markdown تو مسیر docs/src/content/docs/ می‌ذاره، هر صفحه تو frontmatter یه title داره، و هر ریپویی که بخواد تو سایت مستندات بیاد، تاپیک docs رو تو گیت‌هاب می‌گیره. این مسیر رو از Starlight (یعنی تم مستندات Astro) برداشتن تا هر ریپو بتونه سایت مستندات خودش رو هم از همین فایل‌ها بسازه.

any-repo/
  src/
  docs/
    src/content/docs/
      architecture.md

یه ریپوی جدا بقیهٔ کار رو انجام می‌ده. هر ۳۰ دقیقه یه GitHub Action ریپوهایی که تاپیک docs دارن رو با یه API call لیست می‌کنه، tree hash گیت پوشهٔ مستندات هر کدوم رو می‌خونه و اگه عوض شده باشه، فایل‌ها رو sparse clone می‌کنه و سایت رو با Astro Starlight دوباره می‌سازه. خروجی استاتیکه و روی Cloudflare پشت SSO گوگل قرار می‌گیره. نکتهٔ مهم اینه که این ریپو هیچ لیست یا تنظیماتی از ریپوها نداره؛ خود تاپیک گیت‌هاب نقش رجیستری رو بازی می‌کنه.

نویسنده اسم این ایده رو convention-based design گذاشته، یعنی یه مسیر قابل پیش‌بینی می‌شه قرارداد بین ریپو و ابزارهایی که ازش استفاده می‌کنن. ریشه‌ش همون «convention over configuration» تو Ruby on Rails و روتینگ فایل‌محور Next.js هست. قبلاً هم تو Cambridge University Press با همین ایده اپ‌ها رو به Kubernetes برده بودن: یه پوشهٔ infrastructure تو ریشهٔ ریپو برای اجرای یه اپ Node.js کافی بود.

به گفتهٔ نویسنده، فایده‌هاش اینان: همه می‌دونن مستندات کجاست، مستندات تو همون PR کد ریویو می‌شه، صفحهٔ بدون title بیلد رو می‌شکنه، یه جستجوی واحد برای همهٔ ریپوها هست و صاحب هر صفحه همون تیم صاحب ریپوئه. ایجنت‌ها هم همون Markdown رو مستقیم از دیسک می‌خونن. ساختنش هم یه روز کار یه مهندس بود، با یه GitHub App فقط‌خواندنی که توکنش بعد از یه ساعت منقضی می‌شه.

کمبودهاش هم گفته شده: یه صفحهٔ خراب ممکنه تا ۳۰ دقیقه بعد از merge بیلد مرکزی رو بشکنه، پس بهتره یه چک تو خود PR باشه. چیزی هم جلوی پاک کردن صفحه‌ای که ریپوی دیگه بهش لینک داده رو نمی‌گیره، که با یه backlink check حل می‌شه. برای ایجنت‌هایی که مستندات ریپوهای دیگه رو لازم دارن، llms.txt و نسخهٔ Markdown صفحه‌ها و بعداً یه endpoint برای MCP پیشنهاد شده.

نکات کلیدی:

• مسیر ثابت مستندات تو هر ریپو docs/src/content/docs/ هست و هر صفحه باید title داشته باشه.
• ریپوها با تاپیک docs تو گیت‌هاب پیدا می‌شن و هیچ لیست تنظیماتی وجود نداره.
• یه GitHub Action هر ۳۰ دقیقه tree hash پوشه‌ها رو چک می‌کنه و فقط موقع تغییر بیلد می‌گیره.
• سایت با Astro Starlight ساخته می‌شه و روی Cloudflare پشت Google SSO منتشر می‌شه.
• کل سیستم رو یه مهندس تو یه روز ساخت و الان دو ریپو توش منتشر می‌کنن.
• عیب فعلی: خطای یه صفحه تا ۳۰ دقیقه بعد از merge دیده می‌شه، نه تو خود PR.