اگر این مقاله را می‌خوانید به این معنی است که شما در حال حاضر ریپازیتوری ها را در گیت هاب ارسال می‌کنید و حتی ممکن است در پروژه‌های open source همکاری کنید.

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

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

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

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

اول از همه، چرا من به یک فایل README خوب نیاز دارم؟

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

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

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

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

3. به شما کمک می‌کند تا بر روی آنچه که پروژه شما باید تحویل دهد و نحوه تحویل آن تمرکز کنید.

درست همانطور که Friedrich Nietzsche گفته است:

"یک نویسنده خوب نه تنها روح خودش بلکه روح دوستانش را هم تصرف می‌کند".

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

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

می‌بینید، این قدرت نوشتن یک README خوب است.

خوب بیاید برویم شروع کنیم

برای ساختن یک README خوب یک روش درست وجود ندارد. اما یک راه بسیار اشتباه وجود دارد، و آن این است که به هیچ وجه README را درج نکنید.

مراحلی که در زیر ذکر می‌کنیم از بهترین روش‌هایی است که می‌توانید انجام دهید. همانطور که در حرفه خود پیشرفت می‌کنید، ایده‌هایتان در مورد آنچه باعث می‌شود README خوب بنویسید و نحوه بهبود آن، توسعه خواهد یافت.

README باید به "چیست، چرا و چطور" پاسخ دهد:

·       انگیزه شما چیست؟

·       چرا این پروژه را ساختید؟

·       این راه حل چه مشکلی را حل می‌کند؟

·       چه چیزی یاد می‌گیرید؟

·       چه چیزی پروژه شما را برجسته می‌کند؟ اگر پروژه شما ویژگی‌های زیادی دارد. بخش " Features" را اضافه کرده و ویژگی‌ها را در آن لیست کنید.

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

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

عنوان پروژه خود را وارد کنید

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

توضیحات را بنویسید

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

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

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

·       برنامه شما چه کاری انجام می‌دهد،

·       چرا از تکنولوژی‌های استفاده شده استفاده کرده‌اید،

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

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

جدول مفاهیم را اضافه کنید (اختیاری)

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

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

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

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

دستورالعمل‌ها و مثال‌هایی ارائه دهید تا کاربران/همکاران بتوانند از پروژه شما استفاده کنند. در صورت مواجه شدن با مشکل این کار برای آن‌ها آسان خواهد شد؛ آن‌ها همیشه جایی را برای مراجعه دارند.

برای نشان دادن مثال‌هایی از پروژه در حال اجرا می‌توانید اسکرین‌ شات‌ها را در آن نیز قرار دهید.

اعتبارات را وارد کنید

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

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

لایسنس را قرار دهید

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

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

Badge ها

Badgeها ضروری نیستند. اما استفاده از Badge ها فقط یک روش ساده است تا به سایر توسعه دهنگان اطلاع دهید شما می‌دانید چه کاری انجام می‌دهید.

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

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

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

می‌توانید قراردادهای مشارکت و راهنمای مشارکت را بخوانید و طبق آن‌ها این کار را انجام دهید.

تست ها را وارد کنید

شما می‌توانید برای برنامه خود تست بنویسید. سپس مثال‌های کد و نحوه اجرای آن‌ها را ارائه دهید.

جمع بندی

این‌ها مراحل اصلی هستند که شما برای نوشتن اولین README خود نیاز دارید.

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