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


۲۷ خرداد ۱۴۰۰
چگونه یک فایل 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

برچسب‌ها:

خدمات رایگان لیارا

۲.۵ گیگابایت فضای ذخیره‌سازی ابری رایگان

۲.۵ گیگابایت Object Storage سازگار با پروتکل S3 با دیسک‌های SSD به‌صورت رایگان دریافت کنید.

هاست رایگان برای دیتابیس‌

دیتابیس‌های MariaDB، PostgreSQL و Redis را فقط با یک کلیک و به‌صورت رایگان تهیه کنید.

سرویس DNS رایگان

به سادگی دامنه‌تان را اضافه کنید و به صورت رایگان رکورد‌های آن را مدیریت کنید.

۱۰۰ هزار تومان اعتبار اولیه

بعد از ثبت نام در لیارا مبلغ ۱۰۰ هزار تومان اعتبار هدیه دریافت می‌کنید که با توجه به ساعتی بودن هزینه سرویس‌ها، می‌توانید تمامی خدمات پولی را برای چندین هفته رایگان استفاده کنید.

ارسال ۱۰۰ ایمیل تراکنشی رایگان در هر ماه

در سرویس ایمیل لیارا شما می‌توانید تا ۱۰۰ ایمیل رایگان در هر ماه ارسال کنید و فقط برای بیش از آن هزینه پرداخت کنید. (به‌همراه دسترسی SMTP)

هاست رایگان برای انواع وبسایت

تفاوتی ندارد برای وبسایت خود از Node استفاده می‌کنید یا Laravel و Django، در لیارا می‌توانید به صورت کاملا رایگان آن را میزبانی کنید.

توسعه‌دهندگان درباره‌ی ما چه می‌گویند

تجربه کار باliara_cloud@امروز خیلی خوب بود. یکی از سرویس هام رو منتقل کردم روش و راضیم. انقد سریع و جذاب کارم راه افتادم اصن باورم نمیشد! برعکس سرویس های PaaS دیگه با اون همه پیچیدگیشون. دمتون گرم
...

MohammadReza
liara testimonial
keikaavousi

بعد از بسته شدن @fandoghpaas و ناراحتی همه‌مون از اینکه یه سرویس خوب و صادق نمی‌تونه از پس هزینه‌ها بر بیاد، سرویسم رو منتقل کردم به پاس لیارا (https://liara.ir @liara_cloud) . تجربه راحت و خوب. تفاوت‌هایی داشت که کمی کار می‌خواست ولی تا الان کاملا راضی.

jadi
liara testimonial
jadi

یه خسته نباشید باید به تصمیمliara_cloud@بگم،
بعد از چندین روز سرکله زدن با سرویس های مشابه بالاخره تصمیم گرفتم لیارا رو امتحان کنم و باور نمیشه ۱۰ دقیقه بیشتر وقت نبرد،
دمتون گرم.

Arch
liara testimonial
EbadiDev

واسه سرویس PaaS با اختلاف لیارا بهترین رابط کاربری داره و یکی از مزیت‌های سرویس دیتابیس‌شون اینه که خودشون به صورت دوره‌ای بکآپ میگیرن.
...

Ali Najafi
liara testimonial
me_ali_najafi

یکی از کارهای خوبی که جدیداً میکنم اینه که یه دیتابیس روی لیارا میسازم و به پروژه وصل میکنم اینطوری هم خونه و هم محل کار دیتابیس بروز رو دارم و راحت میتونم ادامه بدم کار روliara_cloud@

Navid
liara testimonial
1navid

عاشقliara_cloud@شدم درسته در حد AWS نیست ولی خب تجربه خوبی واسه پروژه های داخل ایران ارائه میده، میتونم رو CD هم اجراش کنم

Amir H Shekari
liara testimonial
vanenshi