نوشتن Readme حرفه ای

چطوری یه readme خیلی خوب برای پروژمون بنویسیم؟

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

3 Likes

فکر نمیکنین این بر خلاف مخازن گیت باش ؟

1 Likes

دوتا مساله هست اینجا.

  • گیت
  • گیتهاب/گیتلب و بقیه‌ی سرویسهای از این قبیل.

خود «گیت» که مشکلی با این قضیه نداره. همونطور که توی manpage گفته شده:

       git - the stupid content tracker

کاری با اینکه چه چیزی و چطوری توش قرار میدیم نداره.

درمورد گیتهاب و گیتلب هم فکر میکنم اصلا برای همین کار طراحی شدن! من پروژه‌ی گیتلب (یا gitea یا…) ندیدم اینطوری باشه ولی چندتا پروژه‌ی گیتهاب دیدم که توی بعضی از دایرکتوریها فایل readme داشتن و گیتهاب اون فایلها رو به صورت پیش‌نمایش نشون میداد زیر لیست فایلها! همونطوری که توی دایرکتوری اصلی پروژه نشون میده.

5 Likes

مثلا pelican-plugins اینطوریه.

به نظرم خیلی شلوغه

اگر کداتون داک مخصوص به خودشو در هر فایل نداره این خیلی جوابه

1 Likes

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

به‌هرحال میخواستم یه نمونه نشون بدم از پروژه‌ای که داخل هر دایرکتوری، یه readme داره و git و github باهاش مشکل ندارن.

بله درست ولی بیشتر نحوه نگارش منظورم بود آیا از نگارش خاصی پیروی میکنن مثلا اینکه توضیحات کجا نوشته میشه یا نحوه استفاده از پروژه

نحوه‌ی استفاده ازش مشخصه و توی یه داکیومنت دیگه توضیح داده شده. داکیومنتی که مربوط به خود pelican میشه.
اینجا فقط توی readme اصلی لیست همه‌ی پلاگینها رو گذاشتن و توی دایرکتوری هر پلاگین هم readme مخصوص به خودش وجود داره.

1 Likes