چگونه یک فایل 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

برچسب‌ها:

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

free liarafree liara

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

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

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

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

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

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

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

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

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

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

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

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

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

همراه شما هستیم

در خصوص سفارش یا استفاده از سرویس‌ها سوالی دارید؟

در تمامی روز‌های هفته کنارتان هستیم.

شماره تماس:
۰۲۵-۳۷۸۳۸۹۴۶