مقدمه
کد خوب به تنهایی کافی نیست؛ مستندات خوب نیز به همان اندازه اهمیت دارد. مستندات به کاربران کمک
می‌کند تا نحوه استفاده از نرم‌افزار شما را یاد بگیرند و به توسعه‌دهندگان دیگر (و خود شما در
آینده) کمک می‌کند تا بفهمند کد چگونه کار می‌کند. گیت‌هاب برای این منظور یک ابزار داخلی قدرتمند و
ساده ارائه می‌دهد: ویکی (Wiki).
هر مخزن در گیت‌هاب می‌تواند یک بخش ویکی اختصاصی داشته باشد که محلی ایده‌آل برای نگهداری مستندات
جامع و طولانی‌تر پروژه است. در این درس، با کاربردها و نحوه استفاده از این ویژگی آشنا می‌شویم.
ویکی چه تفاوتی با فایل README دارد؟
شاید بپرسید چرا به جای فایل README.md که در ریشه پروژه قرار دارد، از ویکی استفاده کنیم؟
هر کدام از این ابزارها جایگاه خود را دارند:
- README.md: این فایل به عنوان صفحه فرود و نقطه ورود اصلی به پروژه شما
عمل می‌کند. هدف آن ارائه یک معرفی سریع، آموزش نصب اولیه و نمایش اطلاعات کلیدی در یک نگاه
است. این فایل باید نسبتاً کوتاه و مختصر باشد.
- Wiki: ویکی برای مستندات عمیق‌تر و جامع‌تر طراحی شده است. این فضا
برای نگهداری راهنماهای مفصل کاربری، مستندات کامل API، آموزش‌های گام به گام، توضیحات
معماری سیستم و هر نوع محتوای طولانی دیگری مناسب است.
به طور خلاصه، README برای «شروع سریع» و Wiki برای «یادگیری عمیق» است.
چگونه یک ویکی بسازیم و مدیریت کنیم؟
استفاده از ویکی بسیار ساده است. برای فعال‌سازی آن، کافیست به تب «Wiki» در صفحه اصلی مخزن خود در
گیت‌هاب بروید. اگر برای اولین بار باشد، گیت‌هاب با یک دکمه از شما می‌خواهد که اولین صفحه خود را
(که معمولاً صفحه Home است) ایجاد کنید.
ایجاد و ویرایش صفحات
ویرایشگر ویکی گیت‌هاب از فرمت Markdown پشتیبانی می‌کند که نوشتن محتوای
ساختاریافته را بسیار آسان می‌سازد. شما می‌توانید صفحات جدیدی برای موضوعات مختلف ایجاد کنید. برای
مثال:
- یک صفحه برای «راهنمای نصب پیشرفته»
- یک صفحه برای «مستندات کامل API»
- مجموعه‌ای از صفحات برای «آموزش قابلیت‌های اصلی»
ایجاد لینک بین صفحات
قدرت یک ویکی در قابلیت لینک‌دهی بین صفحات آن است. شما می‌توانید به سادگی با استفاده از سینتکس
[[Page Title]] یک لینک به صفحه دیگری در همان ویکی ایجاد کنید. این کار به شما اجازه
می‌دهد تا یک ساختار محتوایی منسجم و قابل پیمایش بسازید.
سایدبار و فوتر سفارشی
شما می‌توانید با ایجاد صفحاتی با نام‌های خاص _Sidebar و _Footer، یک منوی کناری و
یک پاورقی سفارشی برای تمام صفحات ویکی خود ایجاد کنید. سایدبار برای ایجاد یک فهرست مطالب (Table
of Contents) کلی برای کل مستندات شما بسیار مفید است.
ویکی به عنوان یک مخزن گیت
یک نکته جالب و قدرتمند در مورد ویکی گیت‌هاب این است که خود ویکی در واقع یک مخزن گیت
جداگانه است! این یعنی شما می‌توانید ویکی را روی کامپیوتر خود clone کرده،
صفحات را به صورت آفلاین در ویرایشگر محبوب خود ویرایش کنید و سپس تغییرات را push نمایید.
این ویژگی به شما اجازه می‌دهد تا تاریخچه کامل تغییرات مستندات خود را داشته باشید و حتی فرآیندهای
بازبینی (مانند Pull Request) را برای تغییرات مهم در مستندات نیز پیاده‌سازی کنید (هرچند
این کار به صورت مستقیم در رابط کاربری ویکی پشتیبانی نمی‌شود و نیازمند کار در خط فرمان است).