ملاحظات الإرشاد

هناك نوعان من ملاحظات الإرشاد:

  1. ملاحظات خاصة بالتمرين (تُعرض لتمرين واحد محدّد في المسار)
  2. ملاحظات خاصة بالمسار (تُعرض في جميع تمارين المسار)

الهدف من هذه الملاحظات هو:

  • تسهيل إرشاد التمرين على المرشدين
  • أن يكون إرشاد التمرين متسقًا بين المرشدين

ماذا تحتوي ملاحظات الإرشاد؟

غالبًا ما تحتوي ملاحظات الإرشاد الخاصة بالتمرين على:

  • أمثلة على حلول معقولة
  • اقتراحات شائعة/أخطاء شائعة
  • نقاط للنقاش

غالبًا ما تحتوي ملاحظات الإرشاد الخاصة بالمسار على:

  • اقتراحات شائعة/أخطاء شائعة (تنطبق على جميع التمارين)
  • روابط لمصادر مفيدة (مثل دليل الأسلوب)

كيفية إضافة ملاحظات الإرشاد

تُخزَّن ملاحظات الإرشاد في مستودع website-copy وفق أنماط تسمية الملفات التالية:

  • ملاحظات إرشاد التمرين: tracks/<track-slug>/exercises/<exercise-slug>/mentoring.md
  • ملاحظات إرشاد المسار: tracks/<track-slug>/mentoring.md

لإضافة ملاحظات إرشاد، أرسل طلب سحب (PR) لإضافة ملف يتبع أنماط تسمية الملفات أعلاه.

لماذا لا توجد ملاحظات الإرشاد في مستودع المسار؟

تختلف صيانة المسار اختلافًا كبيرًا عن كتابة ملاحظات الإرشاد، وتتطلب مهارات مختلفة. لذلك، لا يلزم أن يكون كاتبو ملاحظات الإرشاد هم أنفسهم المشرفين على المسار.

إذا خزّنّا ملاحظات الإرشاد داخل مستودع المسار، لكان على المشرفين الموافقة على أي طلب سحب يتعلق بملاحظات الإرشاد قبل دمجه (أو على الأقل لكانوا يُخطَرون عند كل تغيير في ملاحظات الإرشاد). تخزين ملاحظات الإرشاد في مستودع website-copy يتيح لنا:

  • تقليل العبء على المشرفين على المسار
  • أن يراجع ملاحظات الإرشاد أشخاص مختلفون عن المشرفين على المسار (وقد يتداخل الفريقان)
  • السماح بتكرار أسرع في ملاحظات الإرشاد (غالبًا ما يكون المشرفون على المسار صارمين جدًا عند دمج طلبات السحب)