چگونه یک فایل 'README' خوب در محیط 'GitHub' پروژهتان بنویسید
اگر در حال خواندن این مقاله هستید احتمالاً به این معناست که تا کنون مخازنتان را به سمت 'GitHub' سوق داده‌اید و یا حتی قصد مشارکت در محیط 'Open Source' را دارید.
اگر از 'GitHub' استفاده می‌کنید به این معنی است که باید برای پروژه‌ی خود مستندات خوبی بنویسید تا به دیگران در درک پروژه‌ها کمک کند.
اگر به تازگی استفاده از کنترل نسخه یا همان 'Version Control' را شروع کرده‌اید، فکر نکنید تنها هستید - این راهنما نیز برای شما تهیه شده‌است؛ به شما کمک می‌کند یاد بگیرید که چگونه شروع به نوشتن اسنادی مفید کنید.
صادقانه بگویم، وقتی شروع به قرار دادن پروژه‌هایم در محیط 'GitHub' کردم هیچ ایده‌ای نداشتم که یک فایل 'README' چیست (هرچند آن را در پروژه‌های سایر افراد می‌دیدم).
با گذشت زمان شروع به دنبال کردن سایر توسعه‌دهندگان کردم. تمامشان پروژه‌های جالبی داشتند و به «اوپن سورس» کمک کرده بودند و همه یک وجه اشتراک داشتند: پروژه‌هایشان دارای فایل‌های 'README' مفصل و پر از جزییات بود.
پس علاقه‌ی من به فهمیدن مفهوم و معنی 'README' زیاد شد و تصمیم گرفتم تلاش کنم یکی از این فایل‌ها را به پروژه‌ام اضافه کنم.
در این مقاله خواهیم آموخت فایل 'README' چیست و چگونه یکی از این فایل ها را بنویسیم.
اولاً، چرا به یک فایل خوب 'README' نیاز دارم؟
این فایل، راهنمایی است که به کاربران توضیح مفصلی از پروژهای می‌دهد که در مخزن/«رپوزیتوری» خود قرار داده‌اید.
شاید از خودتان بپرسید چرا باید برای نوشتن یک 'README' خوب وقت بگذارید. این‌ها دلایلی هستند که می‌توانند قانعتان کنند که انجام این کار فکری خوبی است:
۱. یک 'README' خوب به پروژهتان در جهت برجسته شدن در میان سایر پروژه‌ها کمک می‌کند؛ و باید به خوبی خود پروژه باشد.
۲. اولین فایلی است که یک شخص هنگام مواجهه با پروژه‌ی شما آن را مشاهده می‌کند، بنابراین باید نسبتاً خلاصه اما دارای جزییات کافی باشد.
۳. به شما کمک می‌کند تا بر روی آنچه پروژهتان باید ارائه دهد، همچنین چگونی این ارائه تمرکز کنید.
همانطور که فردریش نیچه گفته:
یک نویسنده خوب نه تنها روح خود بلکه روحیه‌ی دوستانش را نیز در خود دارد.
هنگام نوشتن یک 'README'، همیشه به خاطر داشته باشید که برای درک کدی که نوشته‌اید به دوستانتان، یا در این مورد خاص به سایر توسعه‌دهندگان، نیاز دارید.
به عنوان مثال نگاهی به این پروژه بیاندازید:
https://github.com/larymak/GitIntro
همانطور که مشاهده می‌کنید این پروژه فاقد یک فایل 'README' مفصل، توضیحات یا هرگونه راهنمایی است.
با داشتن همچین پروژهای روی 'GitHub' هیچکس نمی‌تواند بفهمد اصلا کارایی آن چیست، فرقی هم ندارد چقدر زمان برای ساختش گذاشته‌اید، درست است؟
اکنون نگاهی به این پروژه بیاندازید:
https://github.com/larymak/Html-Css-Recap
اینجا شما می‌توانید بفهمید پروژه چه کاری می‌کند، دربردارنده‌ی چیست و اگر نیاز به استفاده از آن دارید یا می‌خواهید در توسعه پروژه مشارکت کنید، باید چه کاری انجام دهید.
می‌بینید؟ این قدرت نوشتن یک 'README' خوب است.
پس بیایید شروع کنیم
برای پیکربندی یک فایل 'README'خوب «یک روش درست» وجود ندارد. اما یک راه کاملاً اشتباه وجود دارد و آن این است که به هیچ وجه خود عبارت README را درج نکنید.
قدم‌های زیر از بهترین تمریناتی است که توانستم پیدا کنم.
همانطور که در حرفه‌ی خود پیشرفت می‌کنید، ایده‌های خودتان در زمینه‌ی اینکه چه چیزی باعث ایجاد یک فایل 'README' خوب گشته و چگونه می‌توانید آن را ارتقاء دهید، را توسعه خواهید داد.
یک 'README' باید به پرسش‌های زیر پاسخ دهد:
- انگیزه‌ی شما چه بوده؟
- چرا این پروژه را ساختید؟
- چه مشکلی را حل می‌کند؟
- چه یاد گرفتید؟
- چه چیزی پروژهتان را برجسته می‌کند؟ اگر پروژه‌ی شما ویژگی‌های زیادی دارد، می‌توانید بخشی به نام «ویژگی‌ها» اضافه کرده و موارد مد نظرتان را در این قسمت لیست کنید.
نحوه‌ی نوشتن یک فایل 'README' خوب
این‌ها مراحلی است که باید برای نوشتن فایلتان طی کنید.
عنوان پروژهتان را بگنجانید
این نام پروژه است. عنوان، تمام پروژه را در یک جمله توصیف می‌کند و به مردم کمک می‌کند تا هدف اصلی و مقصود پروژه را متوجه شوند.
توضیحاتی بنویسید
توضیحاتتان جنبه‌ی بسیار مهمی از پروژه‌ی شماست. توضیحی خوش ساخت به شما امکان می‌دهد که کارتان را به سایر توسعه‌دهندگان و همچنین کارفرمایان بالقوه نشان دهید.
توضیحات از مولفه‌های مهم پروژه شماست که اکثر توسعه‌دهندگان تازه کار اغلب از آن چشم‌پوشی می‌کنند.
کیفیت توضیحات 'README' در اکثر مواقع یک پروژه خوب را از پروژهای بد، متمایز می‌کند. پروژهای خوب از فرصت داده شده برای ارائه‌ی توضیحات و دیده شدن، حداکثر استفاده را می‌برد:
- برنامه شما چه کاری انجام می‌دهد،
- چرا از فن‌آوری‌هایی که آن‌ها را در پروژه به کار بردید، استفاده کردید،
- برخی از چالش‌هایی که با آن‌ها مواجه شدید و ویژگی‌هایی که امیدوارید در آینده پیاده‌سازی کنید.
یک 'README' خوب به شما کمک می‌کند تا در میان تعداد زیادی از توسعه‌دهندگانی که کارشان را در 'GitHub' قرار می‌دهند، برجسته شوید.
فهرست مطالب اضافه کنید (اختیاری)
اگر 'README' شما خیلی طولانیست، احتمالاً بخواهید برای تسهیل کار کاربران در یافتن مطلب مورد نظرشان، فهرست مطالبی قرار دهید. این امر به آن‌ها کمک می‌کند تا در قسمت‌های مختلف فایل پیمایش کنند.
چگونه از پروژه‌ی خود استفاده کنید
دستورالعمل و مثال‌هایی فراهم کنید تا کاربران/همکاران بتوانند از پروژه استفاده کنند. در صورتی که با مشکلی مواجه شوند، این امر برایشان کار را راحت خواهد کرد زیرا همیشه محلی برای مراجعه خواهند داشت.
همچنین همیشه می‌توانید برای نشان دادن پروژه در حال اجرا از «اسکرین‌شات» استفاده کنید.
«فهرست نام کمک کنندگان» را در پروژه بگنجانید
اگر به شکل تیمی یا سازمانی روی پروژهای کار کرده‌اید، لیست اسامی همکاران/اعضای تیم خود را تهیه و بارگزاری کنید. همچنین باید پیوندهایی به نمایه یا همان «پروفایل»های آنان در 'GitHub' قرار دهید.
همچنین اگر برای ساخت آن پروژه‌ی بخصوص، آموزش‌هایی را دنبال کرده‌اید باید پیوندهای آن‌ها را نیز در اینجا وارد کنید. این روشی برای نشان دادن قدردانی شما و همچنین کمک به دیگران برای در اختیار داشتن نسخه‌ی دست اول پروژه است.
قسمت مجوز را درج کنید
این بخش پایانی اکثر 'README' هاست. این بخش به سایر توسعه‌دهندگان امکان می‌دهد تا بدانند با پروژه‌ی شما چه کارهایی را می‌توانند و چه کارهایی را نمی‌توانند انجام دهند. اگر برای انتخاب مجوز «لیسانس» به کمک نیاز دارید از این سایت استفاده کنید:
https://choosealicense.com/
بخش‌هایی که در بالا ذکر شدند حداقل الزامات برای یک 'README' خوب هستند. اما شاید بخواهید قسمت‌های زیر را هم اضافه کنید.
نشان‌ها
نشان‌ها ضروری نیستند؛ اما استفاده از آن‌ها راهی ساده است که به سایر توسعه‌دهندگان نشان دهید که می‌دانید دارید چکار می‌کنید.
نمی‌دانید آن‌ها را از کجا تهیه کنید؟ نشان‌های میزبانی شده توسط سایت shields.io را بررسی کنید. ممکن است در حال حاضر درک اینکه هرکدام نمایانگر چه هستند برایتان دشوار باشد، اما به مرور زمان خواهید فهمید.
چگونه می‌توان در پروژه مشارکت کرد
اگر برنامه یا بسته‌ای ایجاد کرده‌اید و دوست دارید سایر توسعه‌دهندگان در آن مشارکت داشته باشند (پروژهای متن‌باز «اوپن‌سورس»)، باید دستورالعمل‌هایی اضافه کنید تا به آن‌ها در مورد چگونگی مشارکت در پروژهتان اطلاعاتی بدهد.
سایت‌های https://www.contributor-covenant.org/ و https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/ برای تنظیم قواعد مد نظرتان به شما کمک خواهند کرد.
آزمون و خطا را در پروژه بگنجانید
چند قدمی فراتر رفته و برای برنامه خود «تست»هایی بنویسید. سپس کدهایی را در قالب مثال فراهم کرده و توضیح دهید چگونه اجرا می‌شوند.
نتیجه‌گیری
این موارد مراحل اصلی است که برای نوشتن اولین 'README' خود نیاز دارید!
حالا که مراحل فوق را طی کرده‌ایم، معتقدم آماده‌اید تا فایل‌های 'README' را برای برجسته کردن پروژهتان به آن‌ها بیافزایید.
اگر هنوز به راهنمایی بیشتر نیاز دارید، می‌توانید این نمونه‌ها را نیز بررسی کنید:
https://www.makeareadme.com/
https://rahuldkjain.github.io/gh-profile-readme-generator/
https://github.com/kefranabg/readme-md-generator
همچنین به راهنمای تهیه شده توسط «ناوندوو پُتکات» نگاهی بیاندازید:
https://github.com/navendu-pottekkat/awesome-readme/blob/master/README-template.md
از کدنویسی لذت ببرید.
