زمانی که برای اولین بار با گیت هاب آشنا شدم، هیچ ایده ای نداشتم که چیست و چه کاری می تواند انجام دهد. سپس در آن یک حساب ایجاد کردم، چون به من گفته شد که هر توسعه دهنده ای باید یک حساب گیت هاب داشته باشد که در آن کدهای خود را push دهد.
برای طولانی ترین زمان به عنوان یک مبتدی هیچ کاری با حسابم انجام ندادم. اما پس از آن، به دلیل علاقه‌ام به فناوری، شروع به دنبال کردن سایر توسعه‌دهندگان و بررسی کار آنها در GitHub کردم. و من متوجه وجه مشترک آنها شدم: همه آنها پروژه های جالبی داشتند و به منبع باز کمک می کردند، اما پروژه های آنها همچنین دارای فایل های README دقیق بود.
بنابراین علاقه من به آنچه یک README بود افزایش یافت و تصمیم گرفتم سعی کنم یکی از آن ها را نیز به پروژه های خود اضافه کنم. من این کار را با عجله انجام دادم بدون اینکه بدانم چگونه باید انجام شود. و راستش اصلا عالی نبود و خیلی با چیزی که می خواستم تفاوت داشت.
و اینگونه بود که برای مدتی ماندگار شد. اما با تمرین و یادگیری مستمر توانستم به یک چیز بهتری تغییر دهم، که تعامل با پروژه را بهبود بخشید و به توسعه دهندگان دیگر کمک کرد تا درگیر شوند.
همچنین مهم است که توجه داشته باشید که یک README خوب به شما کمک می کند تا در میان جمعیت زیادی از توسعه دهندگان که کار خود را در GitHub قرار می دهند برجسته شوید.
در این مقاله، درباره فایل README و نحوه نوشتن آن بیشتر خواهیم آموخت. ابتدا بیایید منظورمان از فایل README را بفهمیم.
فایل README چیست؟
به زبان ساده، می‌توانیم یک فایل README را به‌عنوان راهنما توصیف کنیم که README یک فایل علامت گذاری (md.) و به کاربران شرح مفصلی از پروژه‌ای که روی آن کار کرده‌اید، می‌دهد.
همچنین می‌توان آن را به عنوان مستنداتی با دستورالعمل‌هایی در مورد نحوه استفاده از یک پروژه توصیف کرد. معمولاً دستورالعمل هایی در مورد نحوه نصب و اجرای پروژه خواهد داشت.
شما باید به این فایل اهمیت دهید زیرا این اولین فایلی است که مردم در پروژه شما می خوانند! داشتن یک README خوب همچنین به پروژه شما کمک می کند که برجسته شود زیرا بسیاری از پروژه ها اغلب فاقد README خوب هستند.
برای شما به عنوان یک توسعه دهنده ضروری است که بدانید چگونه پروژه خود را با نوشتن یک README مستند کنید زیرا:
- این اولین فایلی است که شخص هنگام مواجهه با پروژه شما می بیند، بنابراین باید نسبتاً مختصر اما مفصل باشد.
- این پروژه شما را از بسیاری از پروژه های دیگر متمایز می کند. همچنین مطمئن شوید که پروژه شما نیز خوب است.
- این به شما کمک می کند تا روی آنچه پروژه شما باید ارائه دهد و چگونه تمرکز کنید.
همانطور که فردریش نیچه گفته است، مهارت های نوشتن شما را بهبود می بخشد: “یک نویسنده خوب نه تنها روحیه خودش را دارد بلکه روح دوستانش را نیز دارد.”.
در حین کار بر روی یک پروژه، به خاطر داشته باشید که به توسعه دهندگان دیگری نیاز خواهید داشت تا کد شما و آنچه که انجام می دهد را درک کنند. بنابراین همراهی آن با یک راهنمای اضافی واقعا مفید خواهد بود.
به عنوان مثال، در یکی از اولین پروژه من README خوبی نداشت. و حتی اگر پروژه شگفت‌انگیز بود، برای یک مبتدی سخت بود که بفهمد وقتی مخزن من را شبیه‌سازی می‌کرد دقیقاً چه چیزی انتظار می‌رفت. چه کسی می داند شاید حتی ممکن است یک ویروس رمزگذاری شده باشد.
یک پروژه در GitHub، مهم نیست که چقدر شگفت انگیز است، سایر برنامه نویسان مشتاق کار روی آن نیستند و سعی نمی کنند بدون README خوب آن را کشف کنند.
حالا نگاهی به یک پروژه در گیت هاب بیندازید که README خوبی دارد. می‌توانید بفهمید که پروژه چه کاری انجام می‌دهد، چه چیزی مستلزم آن است و اگر نیاز به استفاده از پروژه دارید یا می‌خواهید در آن مشارکت داشته باشید، چگونه شروع کنید.
ببینید، یک README به خوبی نوشته شده چقدر قدرتمند است و چگونه می تواند پروژه شما را تغییر دهد.
بنابراین، بیایید شروع کنیم که چگونه برای شما هم بنویسیم.
چگونه یک README خوب بنویسیم
نکته بسیار مهمی که باید به آن توجه داشت این است که یک راه درست برای ساختار یک README خوب وجود ندارد. اما یک راه بسیار اشتباه وجود دارد و آن این است که اصلاً README را درج نکنید.
از تحقیق و مطالعه فایل های مختلف README، مطمئناً بهترین روش هایی وجود دارد که من پیدا کرده ام. و این چیزی است که من به اشتراک خواهم گذاشت. همانطور که معمولا به خودم می گویم: هر روز یک روز یادگیری است.
بنابراین همانطور که در حرفه خود پیشرفت می کنید و پیشرفت می کنید، ایده های خود را در مورد آنچه که یک README خوب را می سازد و چگونه در آن بهبود می بخشد، توسعه خواهید داد. شاید حتی راهنمای منحصر به فرد خود را پیدا کنید.
قبل از شروع، توجه به این نکته نیز مهم است که وقتی README پروژه خود را می نویسید، باید بتواند به چیستی، چرایی و چگونگی پروژه پاسخ دهد.
در اینجا چند سؤال راهنما وجود دارد که به شما کمک می کند:
انگیزه شما چه بود؟
چرا این پروژه را ساختید؟
چه مشکلی را حل می کند؟
چه یاد می گیرید؟
چه چیزی پروژه شما را متمایز می کند؟
اگر پروژه شما دارای ویژگی های زیادی است، بخش «ویژگی ها» را اضافه کنید و آنها را در اینجا فهرست کنید.
چه چیزی را در README خود قرار دهید
1. عنوان پروژه
این نام پروژه است. کل پروژه را در یک جمله توصیف می کند و به افراد کمک می کند تا بفهمند هدف و هدف اصلی پروژه چیست.
2. شرح پروژه
این یکی از اجزای مهم پروژه شما است که بسیاری از توسعه دهندگان جدید اغلب نادیده می گیرند.
توضیحات شما جنبه بسیار مهمی از پروژه شماست. یک توصیف خوب به شما امکان می دهد کار خود را به دیگر توسعه دهندگان و همچنین کارفرمایان بالقوه نشان دهید.
کیفیت توضیحات README اغلب یک پروژه خوب را از یک پروژه بد متمایز می کند. یک خوب از این فرصت برای توضیح و نمایش استفاده می کند:
برنامه شما چه می کند،
چرا از فناوری هایی که استفاده می کردید استفاده کردید،
برخی از چالش‌هایی که با آن روبرو بودید و ویژگی‌هایی که امیدوارید در آینده پیاده‌سازی کنید.
3. فهرست مطالب (اختیاری)
اگر README شما بسیار طولانی است، ممکن است بخواهید فهرستی از مطالب را اضافه کنید تا کاربران بتوانند به راحتی به بخش های مختلف پیمایش کنند. این باعث می شود خوانندگان به راحتی در پروژه حرکت کنند.
4. نحوه نصب و اجرای پروژه
اگر روی پروژه ای کار می کنید که کاربر باید آن را به صورت محلی در ماشینی مانند "POS" نصب یا اجرا کند، باید مراحل لازم برای نصب پروژه خود و همچنین وابستگی های مورد نیاز را در صورت وجود درج کنید.
توضیح گام به گام نحوه تنظیم و اجرای محیط توسعه ارائه دهید.
5. نحوه استفاده از پروژه
دستورالعمل ها و مثال هایی را ارائه دهید تا کاربران/مشارکت کنندگان بتوانند از پروژه استفاده کنند. این کار را در صورت مواجهه با مشکل برای آنها آسان می کند، آنها همیشه مکانی برای ارجاع به آنچه مورد انتظار است خواهند داشت.
همچنین می‌توانید با گنجاندن موادی مانند اسکرین‌شات‌ها برای نشان دادن نمونه‌هایی از پروژه در حال اجرا و همچنین ساختار و اصول طراحی مورد استفاده در پروژه‌تان، از کمک‌های بصری استفاده کنید.
همچنین اگر پروژه شما نیاز به احراز هویت مانند گذرواژه یا نام کاربری دارد، این بخش خوبی برای گنجاندن اعتبار است.
6. شامل اعتبار
اگر به عنوان یک تیم یا سازمان روی پروژه کار کرده اید، همکاران/اعضای تیم خود را فهرست کنید. همچنین باید پیوندهایی به پروفایل های GitHub و رسانه های اجتماعی آنها نیز اضافه کنید.
همچنین، اگر آموزش‌ها را دنبال کرده‌اید یا به مطالب خاصی اشاره کرده‌اید که ممکن است به کاربر در ساخت آن پروژه کمک کند، پیوندهایی به آنها در اینجا نیز وارد کنید.
این فقط راهی است برای نشان دادن قدردانی خود و همچنین کمک به دیگران برای دریافت نسخه دست اول پروژه.
7. یک لایسنس اضافه کنید
برای اکثر فایل های README، این معمولا آخرین قسمت در نظر گرفته می شود. این به توسعه دهندگان دیگر اجازه می دهد بدانند چه کاری می توانند با پروژه شما انجام دهند و چه کاری نمی توانند انجام دهند.
بسته به نوع پروژه ای که روی آن کار می کنید، انواع مختلفی از License ها را داریم. بسته به موردی که انتخاب می‌کنید، سهمی که پروژه شما دریافت می‌کند را تعیین می‌کند.
رایج ترین مجوز GPL است که به دیگران اجازه می دهد کد شما را اصلاح کنند و از آن برای مقاصد تجاری استفاده کنند.
تا این مرحله، آنچه ما پوشش داده‌ایم حداقل الزامات یک README خوب است. اما ممکن است بخواهید بخش‌های زیر را نیز اضافه کنید تا آن را جذاب‌تر و تعاملی‌تر کنید.
بخش های اضافی README
8. نشان ها (Badges)
نشان‌ها ضروری نیستند، اما استفاده از آنها راهی ساده است که به سایر توسعه‌دهندگان اجازه می‌دهد بدانند که شما می‌دانید چه کار می‌کنید.
داشتن این بخش همچنین می تواند برای کمک به پیوند به ابزارهای مهم مفید باشد و همچنین برخی از آمارهای ساده در مورد پروژه شما مانند تعداد فورک ها، مشارکت کنندگان، مسائل باز و غیره را نشان می دهد.
خوبی این بخش این است که به طور خودکار خود به روز می شود.
نمی دانید آنها را از کجا تهیه کنید؟ نشان های میزبانی شده توسط shields.io را بررسی کنید. آنها تعداد زیادی نشان برای کمک به شما در شروع کار دارند. شما ممکن است متوجه نشوید که همه آنها اکنون چه چیزی را نشان می دهند، اما به مرور متوجه خواهید شد.
9. نحوه مشارکت در پروژه
اگر در حال توسعه یک پروژه منبع باز هستید که به توسعه دهندگان دیگری برای مشارکت در آن نیاز دارید، این بیشتر مفید خواهد بود. می‌خواهید دستورالعمل‌هایی را اضافه کنید تا بدانند چگونه می‌توانند در پروژه شما مشارکت کنند.
همچنین مهم است که مطمئن شوید مجوزی که برای پروژه های منبع باز انتخاب می کنید صحیح است تا از تضادهای بعدی جلوگیری شود. و افزودن دستورالعمل های مشارکت نقش بزرگی ایفا خواهد کرد.
برخی از رایج ترین دستورالعمل ها عبارتند از Contributor Covenant و Contributor راهنمای. این اسناد به شما کمک می کند که هنگام تنظیم قوانین برای پروژه خود نیاز دارید.
10. شامل تست
به پروژه خود و برای درخواست خود تست بنویسید. سپس نمونه کد و نحوه اجرای آنها را ارائه دهید.
این به شما کمک می‌کند نشان دهید که مطمئن هستید و مطمئن هستید که پروژه شما بدون هیچ چالشی کار می‌کند، که باعث می‌شود افراد دیگر نیز به آن اعتماد کنند.
امتیاز اضافی
در اینجا چند نکته اضافی وجود دارد که هنگام نوشتن README باید به آنها توجه کنید:
آن را به روز نگه دارید - این یک تمرین خوب است که مطمئن شوید فایل شما همیشه به روز است. در صورت وجود تغییرات، حتما فایل را در صورت لزوم به روز کنید.
یک زبان را انتخاب کنید - همه ما از کشور های مختلف آمده ایم و همه ما به زبان های مختلفی صحبت می کنیم. اما این بدان معنا نیست که باید کد خود را به زبان محلی ترجمه کنید. نوشتن README به زبان انگلیسی کارساز خواهد بود زیرا انگلیسی یک زبان پذیرفته شده جهانی است. اگر مخاطب هدف شما با زبان انگلیسی آشنا نیست، ممکن است بخواهید در اینجا از ابزار مترجم استفاده کنید.
نتیجه
همه چیزهایی که برای بهبود فایل های README یا حتی شروع نوشتن اولین فایل خود به آن نیاز دارید، وجود دارد.
در این مرحله من مطمئن هستم که شما در موقعیتی هستید که می توانید یک راهنمای تعاملی و اطلاعاتی را به پروژه بعدی خود یا حتی پروژه موجود اضافه کنید و پروژه خود را برجسته کنید.
ابزارهای زیادی وجود دارد که می توانید از آنها برای ایجاد خودکار README برای پروژه خود نیز استفاده کنید، اما همیشه تمرین خوبی است که قبل از حرکت به سمت اتوماسیون آن را به تنهایی امتحان کنید.