مقدمة:
أصبحت البرمجيات المفتوحة المصدر جزءًا من التيار العام، ومضى زمن كانت مشروعاتها لا تجذب إلا المطورين. فاليوم يستخدمها أشخاص في صناعات كثيرة، ولا يمكن توقع معرفة الجميع طريقة استخدامها بمجرد قراءة الشيفرة.
وحتى للمطورين، بمن فيهم أصحاب الخبرة الواسعة في مشروعات أخرى، يمثل التوثيق الجيد أداة مهمة للتهيئة عند الانضمام إلى مجتمع. وكثيرًا ما يبدأ الراغبون في المساهمة بالتوثيق ليتعرفوا إلى المشروع والمجتمع وسير العمل فيه.
التحديات الشائعة
يتفق الجميع على أهمية التوثيق وضرورة إنجازه، لكن بعض طرائق العمل تنتج جودة ضعيفة وتفاوتًا بين أجزائه. فعندما ينشغل المطورون بالشيفرة، لا يبدؤون التوثيق إلا في اللحظة الأخيرة، كالفترة السابقة للإصدار مباشرة.
وكثيرًا ما يتولاه متطوعون يصعب عليهم قول «لا». ومما يزيد الأمر سوءًا نسيان التوثيق بعد الإصدار، فلا يُعدل أو يُحسن، وتتكرر الحلقة المفرغة.
خمس ممارسات جيدة
شاركنا خلال السنوات الماضية في توثيق عدد من المشروعات لدى Linux Foundation Networking وGitLab. ونشارك هنا دروسًا نأمل أن تمنح التوثيق مكانة أساسية في مشروعك.
1. قدّر مساهمات التوثيق بقدر مساهمات الشيفرة. يتركز اهتمام مجتمعات كثيرة على الشيفرة؛ ومن أبسط وسائل تقدير التوثيق مساواته بها في مقاييس المجتمع. فلا ينبغي أن يختلف التقدير باختلاف كون الإيداع commit أو طلب الدمج أو طلب السحب متعلقًا بالشيفرة أو الوثائق. وعند تكريم المساهمين، أدرج الإنجازات المهمة لمن يكتبون التوثيق.
2. ضع الوثائق والشيفرة في مستودع المشروع نفسه. نوصي بشدة بذلك، ومن الوسائل الجيدة تخصيص مجلد رئيسي باسم /doc أو /docs. فهذا ييسر العثور على التوثيق، والأهم أنه يضعه على قدم المساواة مع الشيفرة وموارد المشروع الأخرى.
3. اجعل التوثيق شرطًا للدمج أو لمحطة من محطات الإصدار. إذا امتدت دورة الإصدار ثلاثة إلى ستة أشهر أو أكثر، فنوصي بنقاط مراجعة مرحلية للتوثيق، كما في مثال مجتمع ONAP الذي يحيل إليه الأصل. فيمنع ذلك تأجيله إلى ما قبل الإصدار مباشرة، ويدفع الجميع إلى العمل عليه طوال الدورة. وإذا ناسب المجتمع، يمكن جعله خطوة مطلوبة لكل مساهمة برمجية تؤثر في المستخدمين، كما في مثال GitLab.
4. وحّد عملية المساهمة في الشيفرة والتوثيق. نوصي باتساق الإجراءات واستخدام سلسلة الأدوات نفسها. فكثيرون يبدأون بالتوثيق، الذي لا يتطلب غالبًا معرفة تقنية عميقة بالبرنامج. ومن الجيد أن يتعرف القادم الجديد إلى سير المساهمة ويلتقي أفراد المجتمع خلال تهيئته. وإذا أراد لاحقًا المشاركة في أجزاء أخرى، بما فيها الشيفرة، ينبغي أن تكون الأدوات والإجراءات مألوفة له؛ وإلا اضطر إلى تهيئة ثانية تمثل عقبة غير ضرورية. كما أن اختلاف المسارين قد يوحي بأن التوثيق أقل مكانة من الشيفرة.
5. وثّق عملية المساهمة في التوثيق جيدًا. قد يبدو ذلك بديهيًا، لكنه سهل الإهمال. وبما أن التوثيق مدخل جيد للمساهمين الجدد، اخفض عتبة الدخول ما استطعت. وسيساعد شرح سير المساهمة، وكيفية البدء، وأين تُوجد المهام المناسبة، وكيف تُطلب المساعدة، وغيرها، على شعور القادمين بالترحيب وانخراطهم في المجتمع.
ماذا أيضًا؟
هل لديك نصائح أخرى لمنح التوثيق مكانة أساسية في المجتمعات المفتوحة؟ يدعو المؤلفان قراء الأصل إلى مشاركتها في التعليقات.
يستند المقال إلى عرض «ضمان أن يكون التوثيق مكونًا أساسيًا في المشروعات المفتوحة المصدر»، المقدم في قمة المصدر المفتوح لأمريكا الشمالية في يونيو 2020.
المراجع
- https://www.redhat.com/en/services/training/rh024-red-hat-linux-technical-overview?intcmp=7016000000127cYAAQ
- https://developers.redhat.com/cheat-sheets/advanced-linux-commands/?intcmp=7016000000127cYAAQ
- https://www.linuxfoundation.org/projects/networking/
- https://about.gitlab.com/
- https://wiki.onap.org/display/DW/Guilin+Documentation
- https://docs.gitlab.com/ee/development/contributing/merge_request_workflow.html#definition-of-done
- https://sched.co/c3SY