تغییرات اخیر

در اینجا اطلاعیه‌ها، نسخه‌ها و تغییرات جدید لیارا فهرست می‌شوند.

۰۲۵ ۳۲۰۹۸۰۰۰

آنچه در این مقاله می‌خوانید

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


۲۷ خرداد ۱۴۰۰

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

آنچه در این مقاله می‌خوانید:

  • چرا هر پروژه‌ای به یک فایل README خوب نیاز دارد؟
  • ویژگی‌های یک فایل README خوب
  • جمع‌بندی
  • سوالات متداول
چگونه یک فایل readme خوب برای پروژه‌های github بنویسیم؟

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

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

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

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

اکشن‌های جدید GitHub برای استقرار سریع و بهینه در App Platform را مقاله زیر مطالعه کنید.
اکشن‌های جدید GitHub

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

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

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

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

عنوان پروژه

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

توضیحات

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

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

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

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

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

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

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

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

لایسنس

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

badgeها

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

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

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

GitHub ابزار مدیریت کد و همکاری تیمی، برای بررسی ابزار GitHub مقاله زیر را از دست ندهید.
GitHub چیست؟

جمع‌بندی

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

سوالات متداول

۱. آیا فایل README.md فقط برای پروژه‌های متن‌باز ضروری است؟

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

۲. چه اطلاعاتی را نباید در فایل README قرار داد؟

اطلاعاتی که بسیار فنی، محرمانه یا مربوط به تنظیمات محیط خاصی هستند بهتر است در فایل‌های جداگانه مثل .env.example یا CONTRIBUTING.md قرار گیرند. README باید بیشتر روی معرفی، کاربرد و نحوه استفاده از پروژه تمرکز داشته باشد.

۳. آیا می‌توان چند فایل README برای بخش‌های مختلف یک پروژه ایجاد کرد؟

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

۴. چگونه می‌توان یک فایل README جذاب و حرفه‌ای ایجاد کرد؟

استفاده از ساختار منظم، تیترهای مشخص، مثال‌های کاربردی، اسکرین‌شات‌ها، و badgeها می‌تواند به جذابیت و خوانایی فایل کمک کند. همچنین از زبان ساده و مستقیم استفاده کنید.

۵. تفاوت README با سایر فایل‌های مستندات مانند CONTRIBUTING.md یا CHANGELOG.md چیست؟

README معرفی کلی پروژه را پوشش می‌دهد، در حالی که CONTRIBUTING.md به نحوه مشارکت در پروژه و CHANGELOG.md به تاریخچه تغییرات اشاره می‌کنند. هرکدام نقش خاص خود را در مستندسازی پروژه دارند.

۶. آیا استفاده از زبان فارسی در فایل README برای پروژه‌های GitHub مناسب است؟

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

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

به اشتراک بگذارید

برچسب‌ها: