مقدمة

تخيل أنك وقعت صدفة على مشروع مفتوح المصدر يتماشى تمامًا مع اهتماماتك. أنت حريص على استخدامه أو المساهمة فيه، ولكن من أين تبدأ؟ الإجابة تكمن في التوثيق للمشروع.

فكر الآن في التوثيق مفتوح المصدر كدليل لمساعدة المستخدم على الاستفادة القصوى من المشروع. يرشد المستخدم خلال تفاصيل المشروع، مساعدًا أيضًا على فهم المبادئ الأساسية للمشروع، وكيفية استخدامه وكيفية إضافة مساهماتهم.

في هذه المقالة، سنتناول التوثيق مفتوح المصدر، أنواع التوثيق مفتوح المصدر، ونناقش الأهمية، وأفضل الممارسات لإنشائه، وأدوات لتبسيط عملية إنشاء التوثيق مفتوح المصدر.

ما هو بالضبط التوثيق مفتوح المصدر؟

أولًا وقبل كل شيء، دعونا نحدد مصطلح “مفتوح المصدر”. مفتوح المصدر ببساطة يعني نوعًا من البرمجيات التي يتوفر شفرتها المصدرية بحرية للجمهور لفحصها، تعديلها، تحسينها وتوزيعها. على سبيل المثال: نظام تشغيل Linux، متصفح الويب Firefox، MongoDB وغيرها.

الآن، يُشير التوثيق مفتوح المصدر إلى المواد المكتوبة المرتبطة بالبرمجيات مفتوحة المصدر. يوفر معلومات حول استخدام المنتج، ووظائفه، والصيانة. يتضمن تفاصيل ومعلومات حول ميزات البرامج، وتكوين التثبيت والاستخدام. يتم عادة توفير هذا التوثيق للجمهور جنبًا إلى جنب مع شفرة المصدر.

توفر الوثائق المفتوحة المصدر موردًا شاملاً للمطورين والمستخدمين والمساهمين، حيث تقدم معلومات أساسية حول هدف المشروع وميزاته واستخدامه. في البداية، قد تبدو المشاريع المفتوحة المصدر مرهقة، ولكن بفضل وجود وثائق جيدة، يمكن للمستخدمين والمساهمين فهم المشروع.

أنواع الوثائق المفتوحة المصدر

عادةً ما تحتوي المشاريع المفتوحة المصدر على 3 أنواع من الوثائق. كل منها يلبي احتياجات محددة. وتشمل الوثائق الفنية، وثائق المنتج، والإرشادات.

الوثائق الفنية: هذه الوثائق مخصصة للمطورين. تتعمق في قاعدة الشيفرة، وتشرح واجهة برمجة التطبيقات (API)، وتوضح كيفية استخدام واجهة برمجة التطبيقات الخاصة بالمشروع. كما تتضمن مستندات تمهيدية للمشروع، وإرشادات للمطورين العاملين مع المشروع، وتعليمات لتكوين بيئة التطوير. تعتبر وثائق واجهة برمجة التطبيقات، وأدلة التطوير، وREADME أمثلة رائعة على الوثائق الفنية.

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

الإرشادات: هذه الوثائق مصممة للمساهمين في المشروع. تساعد المساهمين على فهم كيفية التنقل في المشروع. الأنواع الشائعة من إرشادات المشاريع المفتوحة المصدر هي:

1. أدلة المساهمة : إنها مهمة جدًا لأنها تشرح كيفية المساهمة في المشروع، بما في ذلك تقديم التعليمات البرمجية وإصلاحات الأخطاء.

2. أدلة الأسلوب: توفر معلومات حول الأسلوب المفضل، والتنسيق، وقواعد التسمية. إنها تضمن الجودة والاتساق في التعليمات البرمجية والمساهمات.

3. مدونة السلوك : توفر السلوك المتوقع من المساهمين وأعضاء المجتمع.

أهمية وثائق المصدر المفتوح

تعتبر الوثائق الجيدة في غاية الأهمية سواء لمستخدم المشروع أو للمساهم في المشروع. دعونا نلقي نظرة على كيفية مساعدة الوثائق الجيدة للمستخدمين وكذلك المساهمين في مشروع المصدر المفتوح.

للمستخدمين:

1. تحسين تجربة المستخدم : تساعد الوثائق الجيدة المستخدم على فهم كيفية استخدام المشروع بشكل فعال والحصول على أقصى استفادة منه. إنها توفر حلاً أسرع للمشاكل التي قد يواجهها المستخدم عند استخدام المشروع.

2. تبني واستخدام البرنامج بشكل أسهل: تجعل الوثائق واضحة وموجزة من السهل فهم ميزات البرنامج ووظائفه. إنها تقلل من منحنى التعلم وتجعل البرنامج أكثر إمكانية الوصول لمجموعة أوسع من المستخدمين.

3. حل المشكلات : يمكن أن تساعد الوثائق المفصلة المستخدمين في حل مشاكل والعثور على حلول بشكل مستقل. يؤدي ذلك إلى تقليل الاعتماد على الشخصين الداعمين مع تحسين تجربة المستخدم العامة.

4. تقليل تكاليف الدعم: يمكن للوثائق الجيدة المساعدة في تقليل عدد الأسئلة التي تطرحها الدعم، مما يوفر الوقت والموارد للمستخدمين والمطورين على حد سواء.

للمساهمين:

1. فهم أوضح للمشروع : لكي يتمكن المرء من المساهمة في مشروع ما، هناك حاجة إلى فهم هذا المشروع. توفير وثائق جيدة يساعد القارئ على فهم المشروع وكيفية البدء بالمساهمة فيه.

2. تسهيل عملية الإنضمام : تسهل الوثائق الجيدة عملية الإنضمام للمساهمين. فهي تساعدهم على التعرف أكثر على قاعدة الشفرات الخاصة بالمشروع، وسير العمل، والتفاصيل اللازمة التي يحتاجونها لجعل مساهماتهم.

3. تعزيز التعاون: توفير وثائق واضحة وموجزة يخلق أرضية مشتركة للمساهمين، مضمناً بأن الجميع يفهمون أهداف المشروع، والهيكلية، والمعايير البرمجية. يمكن للمساهمين الحصول بسهولة على المعلومات التي يحتاجونها لأداء مهامهم، مما يقلل من التأخيرات والتفاهمات الخاطئة.

أفضل الممارسات لتحقيق وثائق جيدة

من ما ناقشناه حتى الآن، يمكن أن نرى أن كتابة وثائق جيدة لمشروعك مفتوح المصدر أمر بالغ الأهمية. لتحقيق وثائق جيدة تلبي احتياجات مستخدميك ومساهمي المشروع، إليك بعض الأمور التي يجب القيام بها.

1. اكتب بطريقة واضحة وموجزة لتمكين قرائك من فهم ما تقدمه بسهولة. من المهم تجنب استخدام المصطلحات الفنية المعقدة التي قد تربك قرائك، حيث أن جوهر الوثائق هو تحسين تجربة المستخدم

2. نظم وثائقك بطريقة هيكلية ومنظمة. لتحقيق ذلك، يتطلب الأمر ترتيب معلوماتك بشكل منطقي باستخدام العناوين، والعناوين الفرعية، والنقاط المرقمة. يجب أن تتبع وثائقك نمطًا هيكليًا، يجب أن يتدفق كل شيء بشكل جيد من الأعلى إلى الأسفل، ويجب أن يكون من السهل على القراء المتابعة

3. اكتب وفقًا لاحتياجات المستخدم. من الأهمية وضع نفسك في مكانهم، يجب أن تكون وثائقك موردًا مفيدًا، لا عائقًا أمام الدخول. شرح المفاهيم بوضوح قدر الإمكان؛ لا تفترض. يمكنك تضمين مقتطفات الشيفرة لمساعدة في شرح المفاهيم المحددة، وتوقع الأسئلة الشائعة، وتقديم حلول/إجابات مباشرة.

4. حافظ على تحديث وثائقك عندما يتم إجراء تغييرات في المشروع. يجب إرسال الوثائق جنبًا إلى جنب مع الشيفرة، حيث يتم تحديث قاعدة الشيفرة، يجب أيضًا تحديث الوثائق.

5. قدم تعليمات واضحة حول كيفية المساهمة في المشروع. بهذه الطريقة، يمكن للأشخاص الراغبين في المساهمة أن يجدوا طريقهم في المشروع مع جعل تغييراتهم بسهولة أيضًا.

6. تحقق من الأخطاء وعدم التناسق والمعلومات القديمة. كما يُفضل طلب ملاحظات من المستخدمين، فهذا يساعد على تحسين الوثائق.

7. وأخيرًا، ينبغي الاستفادة من الأدوات التي يمكن أن تساعد في تحقيق وثائق جيدة. هناك العديد من الأدوات المتاحة التي يمكنك استخدامها لذلك

الأدوات المتاحة للاستفادة منها في إنشاء وثائق جيدة

كما ذكر سابقًا، هناك العديد من الأدوات التي يمكنك الاستفادة منها لإنشاء وثائق جيدة يمكن للمستخدمين البحث فيها بسهولة وفهمها. وإليك بعض منها.

1. سفنكس : أداة شهيرة لإنشاء وثائق تقنية، خاصة لمشاريع Python. تدعم مختلف تنسيقات الإخراج (HTML، PDF، LaTeX) ولديها بيئة غنية بالامتدادات.

2. دوكسيجن : أداة لإنشاء توثيق واجهة برمجة التطبيقات من تعليقات كود المصدر. تدعم مجموعة متنوعة من لغات البرمجة ويمكنها إنتاج توثيق بصيغ HTML وLaTeX وتنسيقات أخرى.

3. ميك دوكس: مولد توثيق بسيط وسريع وقابل للتكوين يستخدم Markdown لكتابة المحتوى. إنه مناسب تمامًا للمشاريع الصغيرة.

4. اقرأ الوثائق: منصة استضافة للتوثيق المبني باستخدام Sphinx أو ميك دوكس. تبسط توثيق البرمجيات من خلال بناء وتحديث واستضافة الوثائق الخاصة بك.

5. جيت : جيت يسمح لك بتتبع التغييرات على وثائقك مع مرور الوقت. هذا يعني أنه يمكنك بسهولة العودة إلى الإصدارات السابقة إذا لزم الأمر، كما أنه يساعد في منع الحذف العرضي. إنه يساعد في التحديثات المستمرة للوثائق.

يمكنك الاطلاع على وثائق كل أداة لفهم عميق لكيفية عملها وكيفية البدء في استخدامها.

الاستنتاج

لختام، تحدد الوثائق الجيدة مدى فهم واستخدام المشروع بشكل جيد. من الضروري أن تكون هناك وثائق واضحة وموجزة تلبي احتياجات كل شخص يبحث عن استخدام مشروع مفتوح المصدر.

يمكن رؤية من المقال أنه من خلال استثمار الوقت والجهد في إنشاء وثائق شاملة ومنظمة بشكل جيد وسهلة الوصول، لا تحسن فقط تجربة المستخدم ولكن تضمن أيضًا استدامة مشروعك.

في المرة القادمة التي تصادف فيها مشروع مفتوح المصدر يلفت انتباهك، لا تتردد في الاستكشاف؛ ستكون الوثائق دليلك على استخدام المشروع أو المساهمة فيه.

الموارد

https://opensource.googleblog.com/2018/10/building-great-open-source-documentation.html

https://opensource.com/article/20/3/documentation

https://herothemes.com/blog/best-documentation-tools/