HeadlinesBriefing favicon HeadlinesBriefing.com

نموذج GitHub Wiki العكسي: استخدم /docs بدلاً من Wiki

Hacker News •
×

تنبثق مناقشة "هل يجب أن أستخدم الويكي أم مجلد docs على GitHub؟" كل بضعة أشهر. باتباع قاعدة الضربات الثلاث لـ Shawn Wang، يجادل المؤلف بأن استخدام الويكي على GitHub هو نموذج عكسي. الفائدة الوحيدة للويكي هي توفره الدائم، لكنه يفتقر إلى التحكم بالإصدارات، الوصول المحلي، مراجعة الأقران، وخيارات العلامة التجارية. في المقابل، يدمج مجلد /docs التوثيق مع الكود، ويدعم التحكم بالإصدارات، ويمكّن مراجعات طلبات السحب، ويعمل مع أدوات مثل Vale والتدقيق الإملائي. يجب استضافة الصور في مكان آخر لأن الويكي لا يدعم الرفع. لنشر التوثيق، استخدم مجلد /docs مع GitHub Pages وسمة مثل just-the-docs. تجنب فرع gh-pages لإبقاء التوثيق متحكمًا بإصداراته مع الكود. مع نمو المشاريع، قد ينتقل التوثيق إلى مستودع منفصل، لكن المساهمين سيكونون معتادين بالفعل على سير العمل. يدعو المؤلف إلى التعليقات على Twitter.