الوثائق كشيفرة برمجية: كيف أنقذنا معرفتنا من الضياع باستخدام Git؟

يا جماعة الخير، بتذكر مرة كنا في نص “عجقة” شغل على مشروع ضخم لأحد العملاء. كان يوم خميس، والكل بده يروّح بكير، وفجأة ظهرت مشكلة عويصة في جزء حساس من النظام. المسؤول عن هالجزء كان زميلنا “أبو خليل” اللي ترك الشركة قبل شهرين. سألت الفريق: “يا شباب، وين التوثيق تبع هاي المكتبة؟”.

وهنا بدأت المأساة… واحد قال “آخر مرة شفتها كانت على Google Doc بس مش متذكر مين عمله”، والثاني قال “أظن أبو خليل بعتلنا إياها على Slack بس الرسالة ضاعت”، والثالث فتح Confluence ولقينا صفحة فاضية عليها عنوان بس! الدنيا كانت كركبة بمعنى الكلمة. ضيعنا ساعات طويلة ونحنا “نبحر” في الكود ونحاول نفهم منطق “أبو خليل” الغامض. وقتها، صفنت وقلت لحالي: “يا خال، إحنا الكود تبعنا مرتب وموجود على Git، كل تغيير مسجل وكل سطر معروف مين كتبه ومتى. ليش وثائقنا، اللي هي عقل المشروع، مرمية هيك زي اللي ماله صاحب؟”.

تلك الليلة كانت نقطة التحول. قررنا أن نعامل وثائقنا بنفس الاحترام الذي نعامل به شيفرتنا البرمجية. من هنا بدأت رحلتنا مع نهج “الوثائق كشيفرة برمجية” أو “Docs-as-Code”.

ما هو نهج ‘الوثائق كشيفرة برمجية’ (Docs-as-Code)؟

ببساطة شديدة، الحكي بيناتنا، هو أن تستخدم نفس الأدوات والعمليات اللي بتستخدمها في تطوير البرمجيات (زي Git، Markdown، وطلبات السحب) لكتابة وإدارة ومراجعة ونشر التوثيق الفني.

بدل ما تستخدم أدوات معالجة نصوص مغلقة أو منصات Wiki معقدة، أنت بتكتب وثائقك في ملفات نصية بسيطة (مثل Markdown)، بتحفظها في نفس مستودع الكود (Git Repository)، وبتخلي فريقك يراجعها ويساهم فيها بنفس طريقة مراجعة الكود.

ليش وجع هالراس؟ أو بالأحرى، ليش هذا النهج هو الحل؟

قد يبدو الأمر معقداً في البداية، ولكنه يحل مشاكل جوهرية كانت تسبب لنا كوابيس:

1. مصدر واحد للحقيقة (Single Source of Truth)

أكبر مشكلة كانت تواجهنا هي أن التوثيق يعيش في عالم والكود يعيش في عالم آخر. مع Docs-as-Code، التوثيق يسكن بجانب الكود في نفس المستودع. لما مطور يعمل تغيير على ميزة معينة، بيقدر يحدث ملف التوثيق المتعلق بها في نفس الـ Pull Request. هيك بنضمن إنه التوثيق والكود يمشوا إيد بإيد.

2. التعاون والمراجعة على أصولها

بدل ما واحد يغير بالوثيقة على كيفه بدون ما حدا يدري، الآن أي تغيير لازم يمر عبر Pull/Merge Request. هذا يعني أن الفريق كله بيقدر يشوف التغييرات المقترحة، يعلق عليها، يطلب تعديلات، ويوافق عليها قبل ما تصير جزء من التوثيق الرسمي. هذا يرفع جودة التوثيق بشكل خرافي ويمنع المعلومات الخاطئة.

3. تتبُّع التغييرات والتاريخ (Versioning)

مين غيّر هاي الفقرة؟ ومتى؟ وليش؟ أسئلة كانت تضيع إجاباتها في غياهب النسيان. مع Git، كل تغيير موثق. يمكنك استخدام git log لترى تاريخ الملف، وتقارن بين الإصدارات، وحتى ترجع لإصدار قديم لو حصل خطأ. تاريخ وثائقك صار واضحاً وضوح الشمس.

4. الأتمتة والنشر السريع (Automation)

هل تعبت من عملية “انسخ والصق” لنشر التوثيق؟ مع هذا النهج، يمكنك إعداد CI/CD Pipeline. بمجرد دمج التغييرات في الفرع الرئيسي (main branch)، يتم بناء موقع التوثيق تلقائياً ونشره على الإنترنت خلال دقائق. لا تدخل يدوي، لا أخطاء بشرية.

5. إشراك المطورين

بصراحة، المطورون يكرهون الخروج من بيئة عملهم (المحرر، الـ Terminal، Git). لما تطلب منهم يفتحوا أداة Wiki ويسجلوا دخول ويكتبوا في محرر غريب، بتلاقيهم يتهربوا. لكن لما تطلب منهم يعدلوا ملف .md موجود في نفس المشروع، الأمر يصبح جزءاً طبيعياً من عملهم. هذا النهج يشجع المطورين على التوثيق لأنك تتحدث بلغتهم وتستخدم أدواتهم.

كيف نبدأ؟ دليل عملي خطوة بخطوة

طيب يا أبو عمر، حمستنا. كيف نطبق هذا الحكي على أرض الواقع؟ الموضوع أسهل مما تتخيل. خلينا نمشي خطوة بخطوة.

الخطوة الأولى: اختيار الأدوات المناسبة

• لغة التوصيف (Markup Language): أنصح بشدة بـ Markdown. سهلة، بسيطة، ومدعومة في كل مكان.
• مولد مواقع ثابتة (Static Site Generator): هذه هي الأداة السحرية التي تحول ملفات Markdown إلى موقع ويب جميل. هناك خيارات كثيرة، ولكن للمبتدئين، أنصح بـ MkDocs لأنه مبني بلغة Python وسهل جداً. خيارات أخرى قوية تشمل Docusaurus و Hugo.
• نظام التحكم بالإصدارات: Git بلا منازع.
• منصة الاستضافة: GitHub Pages أو GitLab Pages. مجانية وسهلة الإعداد ومتكاملة مع Git.

الخطوة الثانية: مثال عملي باستخدام MkDocs و GitHub Pages

لنفترض أن لدينا مشروعاً ونريد بناء توثيق له.

1. تثبيت MkDocs:

أولاً، تحتاج إلى Python مثبتة على جهازك. ثم، من الـ terminal، اكتب:

pip install mkdocs mkdocs-material

لقد قمنا بتثبيت mkdocs مع ثيم Material الرائع الذي يضيف ميزات كثيرة مثل البحث والتصميم المتجاوب.

2. إنشاء مشروع توثيق جديد:

اذهب إلى مجلد مشروعك الرئيسي وفي الـ terminal، اكتب:

mkdocs new docs-project

سيقوم هذا الأمر بإنشاء مجلد جديد اسمه docs-project يحتوي على ملف الإعدادات mkdocs.yml ومجلد docs الذي ستضع فيه ملفاتك.

3. تعديل الإعدادات وكتابة المحتوى:

افتح ملف mkdocs.yml وعدّله ليبدو هكذا:

site_name: مشروعي الخارق
site_url: https://your-username.github.io/your-repo/
theme:
  name: material
  language: ar
  direction: rtl

nav:
  - 'الرئيسية': 'index.md'
  - 'دليل التثبيت': 'installation.md'
  - 'عن المشروع': 'about.md'

الآن، داخل مجلد docs، أنشئ الملفات index.md و installation.md و about.md واكتب فيها محتوى التوثيق باستخدام Markdown.

4. تشغيل الخادم المحلي للمعاينة:

من داخل مجلد docs-project، شغّل الأمر:

mkdocs serve

الآن افتح المتصفح على العنوان http://127.0.0.1:8000 وستجد موقع التوثيق الخاص بك يعمل محلياً. أي تغيير تحفظه في ملفات الـ .md سيظهر مباشرة في المتصفح.

الخطوة الثالثة: الأتمتة والنشر على GitHub Pages

هنا يأتي السحر الحقيقي. نريد أن يتم نشر الموقع تلقائياً كلما قمنا بعمل push للفرع الرئيسي.

1. إعداد GitHub Actions:

في جذر مشروعك (وليس داخل docs-project)، أنشئ المجلدات والملف التالي: .github/workflows/ci.yml.

2. كتابة الـ Workflow:

ضع الكود التالي في ملف ci.yml:

name: Deploy Documentation

on:
  push:
    branches:
      - main # أو master حسب اسم فرعك الرئيسي

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: 3.x
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force

ماذا يفعل هذا الكود؟

• يعمل هذا الـ workflow تلقائياً عند كل push على فرع main.
• يقوم بسحب آخر نسخة من الكود.
• يقوم بتثبيت Python و MkDocs.
• يشغّل الأمر السحري mkdocs gh-deploy الذي يقوم ببناء الموقع (تحويل الـ Markdown إلى HTML) ثم يدفعه تلقائياً إلى فرع خاص اسمه gh-pages في مستودعك على GitHub.

بعد ذلك، كل ما عليك فعله هو الذهاب إلى إعدادات المستودع على GitHub، ثم إلى قسم “Pages”، واختيار فرع gh-pages كمصدر للنشر. هذا كل شيء! موقع توثيقك أصبح الآن حياً ومتصلاً مباشرة بمستودعك.

نصائح من خبرة ‘أبو عمر’

“استثمروا في وثائقكم كما تستثمرون في شيفراتكم، فكلاهما يروي قصة مشروعكم. شيفرة بدون توثيق جيد هي قصة ناقصة لن يفهمها إلا كاتبها، وربما ولا هو بعد حين.”

• ابدأ صغيراً: لا تحاول نقل كل وثائق الشركة القديمة مرة واحدة. ابدأ بمشروع جديد، أو بجزء صغير وحساس من مشروع قائم. عندما يرى الفريق الفائدة، سيتحمسون للتوسع.
• اجعلها جزءاً من ‘تعريف الإنجاز’ (Definition of Done): في فريقنا، لا يمكن دمج أي Pull Request لميزة جديدة إذا لم يتضمن تحديثاً للتوثيق المتعلق بها. هذا يضمن أن التوثيق لا يتأخر أبداً.
• شجّع على المساهمة من الجميع: معظم أدوات Docs-as-Code (مثل MkDocs Material) تضيف تلقائياً زر “Edit this page” الذي يأخذ المستخدم مباشرة إلى الملف المصدر على GitHub. هذا يسهل على أي شخص، حتى غير المطورين، اقتراح تعديلات.
• لا تنسَ البحث: من أهم ميزات مواقع التوثيق الجيدة هي خاصية البحث. تأكد من أن الأداة التي تختارها توفر بحثاً قوياً وفعالاً.

الخلاصة: من الفوضى إلى النظام 🚀

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

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