چگونه یک فایل README خوب برای پروژه‌های GitHub بنویسیم؟

اضافه کردن یا وجود فایل README.md در زمانی که بخواهید پروژه‌ای را در ریپازیتوری GitHub قرار دهید یا در پروژه‌ای متن باز شرکت کنید بسیار اهمیت پیدا می‌کند زیرا می‌توان به‌کمک این فایل به درک مناسبی از هر پروژه رسید.

چرا هر پروژه‌ای به یک فایل README خوب نیاز دارد؟

فایل README را می‌توان یک راهنما دانست که توضیحات مفصلی از پروژه‌ی قرار گرفته شده در ریپازیتوری GitHub را ارائه می‌دهد. برخی از دلایل متقاعد کننده برای نوشتن یک فایل README خوب به شرح زیر است:

• یک فایل README خوب می‌تواند پروژه‌ی شما را از دیگر پروژه‌های متن باز متمایز کند و به‌همین منظور باید فایل README به‌خوبی خود پروژه باشد.
• این اولین فایلی است که اشخاص هنگام مواجه شدن با پروژه‌ی شما مشاهده می‌کنند بنابراین باید قادر باشید پروژه‌ی خود را به‌طور مختصر اما جزئی شرح دهید.
• می‌توانید به‌کمک این فایل بر روی چگونگی ارائه‌ی پروژه‌ی خود تمرکز کنید.

هنگام نوشتن فایل README درنظر داشته باشید که سایر توسعه‌دهندگان می‌خواهند به‌کمک این فایل، پروژه‌ی شما را درک کنند.

ویژگی‌های یک فایل README خوب

قبل از شروع نوشتن فایل README باید سوال‌های زیر را از خود بپرسید:

• انگیزه‌ی شما از توسعه‌ی این پروژه چه بوده است؟
• این پروژه چه مشکلی را حل می‌کند؟
• مزایا پروژه‌ی شما نسبت به سایر پروژه‌ها چیست؟ اگر پروژه‌های شما ویژگی‌های زیادی دارد می‌توانید یک بخش با عنوان Features به فایل README اضافه کنید.

پس از پاسخ به این سوال‌ها باید جزئیاتی را در نوشتن فایل README رعایت کنید.

عنوان پروژه

شما می‌توانید نام پروژه را در عنوان فایل README وارد کنید که توصیف کننده‌ی کل پروژه است و به سایر افراد در درک هدف اصلی این پروژه کمک می‌کند.

توضیحات

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

• برنامه‌ی شما چه کاری انجام می‌دهد؟
• دلیل شما برای استفاده از فناوری‌های فعلی چه بوده است؟
• با چه چالش‌های روبرو شده‌‌اید و چه ویژگی‌های امیدوار کننده‌ای در آینده به این پروژه اضافه می‌شود؟

فهرست مطالب (اختیاری)

اگر فایل README شما بسیار طولانی باشد، بهتر است فهرست مطالب را به فایل README پروژه‌ی خود اضافه کنید تا کاربران راحت‌تر به آنچه که نیاز دارند، دسترسی پیدا کنند.

نحوه‌ی نصب و پیکربندی پروژه

اگر پروژه‌ی شما یک نرم‌افزار یا برنامه‌ای است که نیاز به نصب یا پیکربندی داشته باشد باید مراحل لازم برای نصب و پیکربندی پروژه را در فایل README قرار دهید.

چگونگی استفاده از پروژه

دستورالعمل‌هایی ارائه دهید که سایر توسعه‌دهندگان یا حتی کاربران عادی قادر باشند از پروژ‌ه‌ی شما استفاده کنند. همچنین می‌توانید از تصاویری برای نشان دادن پروژه‌های در حال اجرا استفاده کنید.

لایسنس

اضافه کردن لایسنس به پروژه باعث می‌شود تا سایر توسعه‌دهندگان بدانند چه کارهایی را می‌توانند با پروژه‌ی شما انجام دهند.

badgeها

اضافه کردن badgeها ضروری نیست اما به‌کمک آن‌ها می‌توانید برخی جزئیات کلیدی را به ساده‌ترین شکل ممکن به فایل README اضافه کنید.

نحوه‌ی مشارکت در پروژه

اگر برنامه یا پکیجی ایجاد کرده‌اید و می‌خواهید سایر توسعه‌دهندگان در توسعه‌ی پروژه‌ی متن باز شما مشارکت داشته باشند باید دستورالعمل‌های مشخصی را در فایل README قرار دهید.

جمع‌بندی

اگر مواردی که در این مقاله به آن‌ها اشاره شد را رعایت کنید می‌توان گفت که قدم‌های اصلی برای داشتن یک فایل README خوب را برداشته‌اید و به این شکل بازخوردهای بهتری دریافت خواهید کرد.

منبع: https://www.freecodecamp.org/news/how-to-write-a-good-readme-file