README چیست و چگونه یک README حرفه‌ای بنویسیم؟

اولین چیزی که بسیاری از بازدیدکنندگان مخزن می‌بینند README است. اگر خالی، کهنه، یا پر از قول بدون دستور اجرا باشد، حتی کد خوب اعتماد نمی‌سازد. اگر دقیق و قابل اجرا باشد، onboarding کوتاه‌تر و مشارکت کم‌اصطکاک‌تر می‌شود.

طبق مستندات GitHub دربارهٔ README، این فایل برای گفتن این است که پروژه چرا مفید است، با آن چه می‌توان کرد، و چگونه می‌توان استفاده کرد. در کنار License، Citation، راهنمای مشارکت و Code of Conduct، انتظارات پروژه را روشن می‌کند.

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

پاسخ کوتاه

README سند ورودی مخزن است که معمولاً به زبان Markdown نوشته می‌شود و GitHub آن را در صفحهٔ اصلی مخزن رندر می‌کند. محتوای رایج طبق Docs: پروژه چه می‌کند، چرا مفید است، چگونه شروع کنیم، کجا کمک بگیریم، و چه کسانی نگهداری می‌کنند. فایل را در .github، ریشه، یا docs بگذارید؛ اولویت نمایش به همین ترتیب است اگر چند README وجود داشته باشد.

README حرفه‌ای کوتاه، قابل اجرا، بدون کلید واقعی، و هم‌تراز با واقعیت کد است. جزئیات بلند را به Wiki یا docs عمیق‌تر ببرید. خودِ GitHub می‌گوید README فقط اطلاعات لازم برای شروع استفاده و مشارکت را نگه دارد.

README قول onboarding است؛ اگر دستورهایش روی ماشین تمیز اجرا نشوند، تبلیغ است نه مستند.

GitHub README را کجا می‌شناسد؟

• اولویت نمایش: پوشهٔ .github، سپس ریشه، سپس docs.
• محتوای رندرشدهٔ بیش از حدود 500 KiB کوتاه می‌شود.
• README هم‌نام کاربر در ریشهٔ مخزن عمومی پروفایل می‌تواند روی صفحهٔ پروفایل ظاهر شود.

از لینک نسبی برای ارجاع به فایل‌های داخل مخزن استفاده کنید تا در Clone هم کار کند؛ Docs لینک نسبی را توصیه می‌کند.

ساختار پیشنهادی عملی

1. نام پروژه و یک پاراگراف هدف.
2. وضعیت: پایدار، بتا یا آرشیو — صادقانه.
3. پیش‌نیازها: زبان، نسخه، سرویس‌های خارجی.
4. نصب و اجرای سریع با دستورهای کپی‌شدنی.
5. پیکربندی: فهرست متغیرهای محیطی با .env.example — بدون مقدار واقعی.
6. تست: چگونه تست را اجرا کنیم.
7. ساختار پوشه‌ها در حد لازم، نه درخت عظیم.
8. مشارکت: لینک به CONTRIBUTING در صورت وجود.
9. امنیت: لینک به SECURITY.md برای گزارش آسیب‌پذیری.
10. License و نگهداری‌کنندگان.

همهٔ بخش‌ها برای هر مخزن اجباری نیستند. یک سرویس داخلی ممکن است بخش OSS نداشته باشد؛ یک کتابخانهٔ عمومی بدون License سردرگم می‌کند.

جدول کیفیت README

README و امنیت

وسوسهٔ گذاشتن کلید در README برای راحتی همکار همان نشت است — مخصوصاً در Public. به‌جای آن .env.example و توضیح محل Secret store. اگر مخزن Public است، SECURITY.md کمک می‌کند گزارش آسیب‌پذیری مسیر داشته باشد.

چگونه بنویسیم که خوانده شود؟

• اول مخاطب را انتخاب کنید: مصرف‌کنندهٔ کتابخانه، Contributor، یا همکار داخلی.
• Quickstart را بالای جزئیات معماری بگذارید.
• جمله‌های کوتاه؛ لیست برای مراحل.
• از تزئین سنگین که محتوا را عقب می‌اندازد بپرهیزید.
• هر Sprint که نصب عوض شد، README را در همان PR به‌روز کنید.

اگر سند طولانی شد، توصیهٔ GitHub را جدی بگیرید: شرح عمیق را به Wiki یا پوشهٔ docs منتقل کنید و از README لینک دهید.

قالب حداقلی

markdown

# نام پروژه یک پاراگراف هدف. ## Quickstart cp .env.example .env npm install npm run dev ## متغیرهای محیطی ببینید .env.example ## تست npm test ## License نام مجوز.

مالکیت README

بدون مالک، README می‌میرد. در تیم کوچک، Tech Lead یا Maintainer مسئول است که PRهای شکستن نصب، README را هم لمس کنند. در Code Review بپرسید: آیا کسی از صفر با همین README بالا می‌آید؟

README داخلی در برابر عمومی

برای مخزن Private سازمانی، README هنوز ارزشمند است: مسیر دسترسی، لینک Runbook، و صاحب سرویس. لحن می‌تواند مستقیم‌تر باشد، ولی باز هم Secret را در متن نگذارید. برای Public، License و مسیر گزارش امنیت پررنگ‌تر می‌شوند.

اگر چند مخاطب دارید، یک README کوتاه عمومی و یک سند داخلی جدا بهتر از یک فایل دوگانهٔ گیج‌کننده است.

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

README ورودی اعتماد و سرعت onboarding است. GitHub آن را برای توضیح چیستی، چرایی، شروع کار، کمک و نگهداری به‌رسمیت می‌شناسد. حرفه‌ای بودن یعنی قابل اجرا، هم‌تراز کد، بدون Secret، و با لینک به اسناد عمیق‌تر وقتی لازم است.

امروز: Quickstart را روی یک پوشهٔ خالی آزمایش کنید و همان‌جا اصلاح کنید.

README برای مخاطب‌های مختلف

مصرف‌کنندهٔ کتابخانه می‌خواهد نصب، مثال حداقلی و قرارداد API را ببیند. Contributor می‌خواهد مسیر تست، لینت و قواعد PR را بداند. همکار داخلی ممکن است به لینک Runbook و صاحب on-call نیاز داشته باشد. اگر همه را در یک سطح مخلوط کنید، هیچ‌کس سریع به جواب نمی‌رسد. از فهرست بالای صفحه به بخش‌ها لینک دهید.

در مخازن چندزبانه، یک README به زبان اصلی تیم و در صورت نیاز ترجمهٔ خلاصه بهتر از دو نسخهٔ ناهمگام است که دائم از هم عقب می‌مانند.

نشان‌ها، اسکرین و رسانه

نشان Build و پوشش تست وقتی به Pipeline واقعی وصل باشند مفیدند؛ تزئین صرف اعتماد جعلی می‌سازد. اسکرین UI باید با نسخهٔ فعلی هم‌خوان باشد و ترجیحاً دادهٔ جعلی نشان دهد. ویدیوی بلند جای Quickstart متنی را نمی‌گیرد؛ مکمل است.

هم‌ترازی با License و امنیت

README بدون اشاره به License در پروژهٔ عمومی سوال حقوقی می‌سازد. یک خط نام مجوز و لینک فایل LICENSE کافی است. برای امنیت، مسیر گزارش آسیب‌پذیری را لینک کنید تا افراد خوب کلید را در Issue عمومی Paste نکنند.

نگهداری README در جریان کار

1. در قالب PR یک چک‌باکس: آیا نصب عوض شد؟ README به‌روز شد؟
2. هر فصل یک نفر غریبه با README از صفر نصب را امتحان کند.
3. لینک‌های شکسته را در CI یا با ابزار لینک‌چک دوره‌ای بیابید.
4. اگر بخش معماری طولانی شد، به docs منتقل و از README لینک دهید.

اشتباه‌های محتوایی رایج

• قول پشتیبانی ۲۴ ساعته بدون کانال واقعی.
• دستورهایی که فقط روی ماشین نویسنده با مسیر مطلق کار می‌کنند.
• نسخهٔ زبانی که با قفل وابستگی نمی‌خواند.
• کپی‌پیست از قالب دیگر بدون حذف بخش‌های نامربوط.

ارتباط README با بقیهٔ اسناد

README دروازه است نه انبار. جزئیات API، ADR و Runbook را بیرون نگه دارید و از دروازه به آن‌ها راه بدهید. این مدل با توصیهٔ GitHub برای سپردن متن بلند به Wiki هم‌راستاست و با مقالهٔ Documentation کامل می‌شود.

منابع و مراجع

• 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 با مستندات کامل سیستم، مقالهٔ ۰۸۶ را بخوانید.