نحوه نگارش readme عالی برای پروژه

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

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

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

فایل README چیست؟

README همانطور که از نامش پیداست: “read me” اولین فایلی است که باید هنگام شروع یک پروژه جدید بخواند. این فایل مجموعه ای از اطلاعات مفید در مورد یک پروژه و نوعی کتابچه راهنمای کاربر است. یک فایل متنی README در مکان های مختلف ظاهر می شود و نه تنها به برنامه نویسی اشاره دارد. فایل README اضافه شده در گیت هاب در زیر لیست فایل های موجود در یک repo ظاهر می شود.

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

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

علت نیاز به یک فایل README خوب

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

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

یک نویسنده خوب نه تنها روحیه خودش را دارد، بلکه روح دوستانش را نیز دارد. ” فردریش نیچه “

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

با چنین پروژه هایی در GitHub هیچ کس نمی تواند بفهمد که چه کاری انجام می دهد مهم نیست که چقدر زمان برای ایجاد آن صرف کرده اید.

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

نحوه نوشتن یک فایل README خوب

در ادامه مراحلی وجود دارد که باید برای نوشتن README خود طی کنید.

درج عنوان پروژه خود

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

نگارش یک توضیحات مختصر

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

کیفیت توضیحات README اغلب یک پروژه خوب را از یک پروژه بد متمایز می کند. یک توسعه دهنده خوب از این فرصت برای توضیح و نمایش استفاده می کند. بهتر است که موارد زیر را حتما در توضیحات خود لحاظ نمایید:

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

یک README خوب به شما کمک می کند تا در میان جمعیت زیادی از توسعه دهندگانی که کار خود را در گیت هاب قرار می دهند برجسته شوید.

افزودن فهرست مطالب (اختیاری)

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

نحوه نصب پروژه خود

اگر پروژه شما نرم افزار یا برنامه ای است که نیاز به نصب دارد، باید مراحل لازم برای نصب پروژه خود را در نظر بگیرید. شرح گام به گام نحوه اجرای محیط توسعه را ارائه دهید. توجه داشته باشید اگر نرم افزار یا برنامه شما جهت اجزا شدن به زیر ساخت خاصی نیاز دارد حتما آن ها را نیز لحاظ نمایید.

نحوه استفاده از پروژه خود

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

شامل اعتبارات

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

فهرست کردن مجوز ها

این آخرین بخش اکثر README ها است. توسعه دهندگان دیگر اجازه می دهد بدانند چه کاری می توانند با پروژه شما انجام دهند و چه کاری نمی توانند انجام دهند.

بخش های ذکر شده در بالا حداقل برای یک README خوب هستند. اما ممکن است بخواهید بخش های زیر را نیز به آن اضافه کنید.

نشان ها

نشان ها لازم نیست. اما استفاده از نشان‌ها تنها راهی ساده است تا به دیگر توسعه‌دهندگان بفهمانید که می‌دانید چه کار می‌کنید. برای تهیه آن ها می توانید نشان های میزبانی شده توسط shields.io را بررسی کنید. شما ممکن است متوجه نشوید که همه آن ها اکنون چه چیزی را نشان می دهند، اما به مرور متوجه خواهید شد.

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

بهترین پالت های رنگی وب سایت در سال ۲۰۲۱

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

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