چگونه یک فایل 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
توسعهدهندگان دربارهی ما چه میگویند
تجربه کار باliara_cloud@امروز خیلی خوب بود. یکی از سرویس هام رو منتقل کردم روش و راضیم. انقد سریع و جذاب کارم راه افتادم اصن باورم نمیشد! برعکس سرویس های PaaS دیگه با اون همه پیچیدگیشون. دمتون گرم
...
MohammadReza
keikaavousi
بعد از بسته شدن @fandoghpaas و ناراحتی همهمون از اینکه یه سرویس خوب و صادق نمیتونه از پس هزینهها بر بیاد، سرویسم رو منتقل کردم به پاس لیارا (https://liara.ir @liara_cloud) . تجربه راحت و خوب. تفاوتهایی داشت که کمی کار میخواست ولی تا الان کاملا راضی.
jadi
jadi
یه خسته نباشید باید به تصمیمliara_cloud@بگم،
بعد از چندین روز سرکله زدن با سرویس های مشابه بالاخره تصمیم گرفتم لیارا رو امتحان کنم و باور نمیشه ۱۰ دقیقه بیشتر وقت نبرد،
دمتون گرم.
Arch
EbadiDev
واسه سرویس PaaS با اختلاف لیارا بهترین رابط کاربری داره و یکی از مزیتهای سرویس دیتابیسشون اینه که خودشون به صورت دورهای بکآپ میگیرن.
...
Ali Najafi
me_ali_najafi
یکی از کارهای خوبی که جدیداً میکنم اینه که یه دیتابیس روی لیارا میسازم و به پروژه وصل میکنم اینطوری هم خونه و هم محل کار دیتابیس بروز رو دارم و راحت میتونم ادامه بدم کار روliara_cloud@
Navid
1navid
عاشقliara_cloud@شدم درسته در حد AWS نیست ولی خب تجربه خوبی واسه پروژه های داخل ایران ارائه میده، میتونم رو CD هم اجراش کنم
Amir H Shekari
vanenshi