Documentation چیست و چرا پروژه‌های حرفه‌ای بدون آن آسیب‌پذیر می‌شوند؟

Documentation (مستندات) مجموعهٔ نوشته‌ها، نمودارها و مثال‌هایی است که به انسان کمک می‌کند سیستم را بسازد، به‌کار گیرد، تغییر دهد و در حادثه نجات دهد. کد منبع حقیقت رفتار فعلی است؛ مستند حقیقت قصد، قرارداد، و مسیر بازیابی است. وقتی فقط کد هست، هر نفر جدید باید با آزمون و خطا و پرسش از «کسی که می‌داند» پیش برود.

پروژه‌های حرفه‌ای بدون مستند لزوماً فردا سقوط نمی‌کنند؛ آسیب‌پذیر می‌شوند: onboarding طولانی، تصمیم‌های تکراری، outage طولانی‌تر، و وابستگی خطرناک به یک یا دو نفر. این مقاله لایه‌های مستند، حداقل عملی، و نشانه‌های سند مرده را می‌گوید.

README لایهٔ ورودی است (مقالهٔ ۰۸۴)؛ کامنت لایهٔ موضعی کد است (۰۸۵). Documentation فراتر از هر دوست: قرارداد API، معماری، Runbook عملیات، و تصمیم‌های ثبت‌شده.

پاسخ کوتاه

Documentation یعنی انتقال دانش لازم برای استفاده و تغییر سیستم بدون وابستگی شکننده به حافظهٔ افراد. نبودش پروژه را در برابر ترک نیرو، رشد تیم، و حادثهٔ Production آسیب‌پذیر می‌کند — نه چون «استاندارد ISO کم است»، بلکه چون زمان بازیابی و هزینهٔ اشتباه بالا می‌رود.

حداقل سالم برای تیم کوچک: README قابل اجرا، .env.example، یک صفحهٔ معماری با مرز سرویس‌ها، قرارداد API برای مصرف‌کننده‌ها، و Runbook برای دو سه حادثهٔ پرتکرار. بهتر است کم و درست باشد تا ویکی عظیم کهنه.

مستند کامل افسانه است؛ مستند کافی برای نفر بعدی و ساعت ۳ صبح واقعی است.

لایه‌های مستند

طبق GitHub، README باید اطلاعات لازم برای شروع استفاده و مشارکت را داشته باشد و متن طولانی‌تر برای Wiki مناسب‌تر است. همین اصل را به بقیهٔ لایه‌ها تعمیم دهید: هر سند یک شغل داشته باشد.

چرا نبود مستند آسیب‌پذیری است؟

• Bus Factor: اگر فقط یک نفر می‌داند deploy چگونه است، مرخصی او ریسک کسب‌وکار است.
• تکرار باگ: بدون ثبت علت ریشه‌ای، یک حادثه دوباره رخ می‌دهد.
• ادغام اشتباه: مصرف‌کنندهٔ API بدون قرارداد، به رفتار اتفاقی وابسته می‌شود.
• امنیت: بدون مسیر گزارش و بدون فهرست Secretها، نشت دیر کشف می‌شود.
• هزینهٔ استخدام: هر نیروی جدید هفته‌ها می‌پرسد به‌جای اینکه اجرا کند.

این‌ها شعار کیفیت نیستند؛ مستقیم به زمان downtime و هزینهٔ نیروی انسانی وصل‌اند.

حداقل عملی بر اساس اندازهٔ تیم

۱ تا ۳ نفر

1. README با Quickstart واقعی.
2. .env.example و gitignore درست.
3. یک فایل docs/overview.md با نمودار سادهٔ اجزا.
4. چک‌لیست Deploy در ده خط.

۴ تا ۱۵ نفر

1. همهٔ بالا به‌علاوهٔ قرارداد API.
2. Runbook برای: سرویس بالا نمی‌آید، خطا در پرداخت، نشت Secret.
3. ADR برای تصمیم‌های برگشت‌ناپذیر (دیتابیس، مرز سرویس).
4. مالک سند در CODEOWNERS یا جدول ساده.

بزرگ‌تر

پورتال مستند، نسخه‌بندی، و ارتباط اجباری تغییر قرارداد با نسخهٔ API. ابزار مهم است؛ انضباط مهم‌تر.

ADR به زبان ساده

Architecture Decision Record یک صفحهٔ کوتاه است: زمینه، تصمیم، پیامد. وقتی کسی شش ماه بعد می‌پرسد «چرا این صف نه آن یکی؟» جواب در Git است نه در حافظه. ADR را برای هر انتخاب کوچک ننویسید؛ برای تصمیم‌هایی بنویسید که برگشتشان گران است.

Runbook و ساعت ۳ صبح

Runbook مراحل تشخیص و اقدام است، نه مقالهٔ آموزشی. علائم، لینک داشبورد، فرمان‌های مجاز، و کی باید Escalate کرد. بعد از هر حادثهٔ واقعی، Runbook را در همان هفته به‌روز کنید — وگرنه مستند نمایشی می‌شود.

نشانهٔ مستند مرده

• دستور نصب با نسخهٔ زبان فعلی نمی‌خواند.
• لینک‌های شکسته بیش از چند هفته مانده‌اند.
• فقط در onboarding اول خوانده می‌شود و بعد کسی لمسش نمی‌کند.
• با کد در یک PR عوض نمی‌شوند؛ «بعداً می‌نویسیم».

در Review، شکستن رفتار عمومی بدون لمس docs باید همان‌قدر ناراحت‌کننده باشد که شکستن تست.

مستند و AI

ابزارهای AI در نوشتن پیش‌نویس README یا خلاصهٔ PR کمک می‌کنند، ولی مسئولیت صحت با انسان است. Secret را به مدل ندهید؛ و خروجی را روی مسیر واقعی اجرا کنید. مستند تولیدشدهٔ بررسی‌نشده می‌تواند خطرناک‌تر از نبود مستند باشد چون اعتماد جعلی می‌سازد.

مخالفت رایج و پاسخ

«وقت نداریم.» هزینهٔ نوشتن ده خط Runbook کمتر از دو ساعت قطعی تکراری است. «کد واضح است.» کد رفتار را نشان می‌دهد نه قرارداد و قصد را. «کسی نمی‌خواند.» اگر در مسیر کار (PR template، لینک از خطا، onboarding) نباشد، حق با شماست — جایش را عوض کنید نه اینکه حذفش کنید.

جمع‌بندی برای تصمیم

Documentation لایهٔ بقای دانش است. بدون آن پروژه به افراد گره می‌خورد و در برابر رشد و حادثه شکننده می‌شود. کمینهٔ عملی را با README، قرارداد، ADRهای مهم و Runbook شروع کنید و سند را در همان PR تغییر نگه دارید.

این هفته یک Runbook برای محتمل‌ترین حادثهٔ سرویس‌تان بنویسید — حتی اگر یک صفحه باشد.

مستند به‌عنوان بخشی از Definition of Done

اگر Done فقط یعنی روی Production است، دانش جابه‌جا نشده است. برای تغییرات بیرونی‌شونده، به‌روزرسانی README یا changelog یا قرارداد API را بخشی از Done بدانید. برای تغییرات عملیاتی، Runbook. بدون این قلاب، مستند همیشه کار فردا می‌ماند.

قالب PR با چک‌باکس مستند ساده و مؤثر است؛ ابزار گران لازم نیست.

اندازه‌گیری بدون نمایش کاذب

تعداد صفحات ویکی معیار سلامت نیست. معیارهای بهتر: زمان رسیدن نیروی جدید به اولین Commit مفید، تعداد سوالات تکراری در چت که با یک لینک سند باید جواب داده می‌شد، و مدت بازیابی حوادث مشابه قبل و بعد از Runbook. اگر عدد ندارید، با نظرسنجی کیفی کوتاه شروع کنید.

مستند API و سازگاری

قرارداد API باید نسخه، فیلدهای اجباری، خطاها و مثال داشته باشد. وقتی رفتار عوض می‌شود، نسخه یا تاریخ منسوخ‌شدن را اعلام کنید. مصرف‌کنندهٔ داخلی هم مشتری است؛ شکنندگی قرارداد داخلی به اندازهٔ عمومی هزینه دارد.

دانش ضمنی را شکار کنید

بعد از هر outage یا تصمیم معماری داغ، سی دقیقه برای نوشتن کافی است. منتظر سند کامل نمانید. نیم‌صفحه با تاریخ و نویسنده از حافظهٔ شفاهی بهتر است. بعداً می‌توانید ادغام و مرتب کنید.

ضدالگوها

• ویکی بدون مالک که فقط تبلیغ اسپرینت صفر است.
• اسلایدهایی که در Git نیستند و پیدا نمی‌شوند.
• مستند فقط برای ممیزی سالانه بدون استفادهٔ عملیاتی.
• تکرار عین کد در سند بدون چرایی.

نقش PM و عملیات

PM می‌تواند FAQ کاربر و محدودیت ویژگی را مالک شود. عملیات مالک Runbook و escalation است. مهندسی مالک قرارداد و ADR. تفکیک مالکیت جلوی فایل یتیم را می‌گیرد. در تیم سه نفره یک نفر چند کلاه دارد؛ باز هم نام مالک را روی سند بنویسید.

گام بعدی بعد از این مقاله

فهرست سه سند که اگر فردا یکی از اعضای کلیدی نباشد بیشترین درد را می‌سازند. همان سه را این ماه بنویسید یا به‌روز کنید. سپس به امنیت مخزن و Secret برگردید تا دانش و ایمنی با هم جلو بروند.

منابع و مراجع

• GitHub Docs — About the repository README file — https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes

README نقطهٔ ورود است؛ این مقاله نقشهٔ لایه‌های بعد از ورود را کشید. برای امنیت مخزن به ۰۸۰–۰۸۲ برگردید.