مقدمة حول سير العمل

توثيق الأكواد (Documentation) هو الحلقة الأضعف في العديد من المشاريع البرمجية؛ فالكود يتطور باستمرار بينما يبقى التوثيق قديماً. توليد توثيق تلقائي من تعليقات الكود يحل هذه الأزمة بربط تحديثات الكود بتحديثات التوثيق آلياً، مستفيداً من التعليقات البرمجية والذكاء الاصطناعي.

الهدف من سير العمل

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

الأدوات والتقنيات المستخدمة

GitHub Webhook: لالتقاط التغييرات المضافة حديثاً.
n8n: لإدارة مسار استخراج التعليقات وتوليد التوثيق.
Ollama: لتشغيل نموذج لغوي يقرأ الكود والتعليقات ويحولها إلى شروحات منظمة وسهلة الفهم.
Docusaurus: المنصة الشهيرة والمفتوحة المصدر لبناء ونشر مواقع التوثيق.

تفاصيل تنفيذ سير العمل

مستوى الصعوبة: متوسط (Intermediate).
الوقت المتوقع للإعداد: يوم عمل لتهيئة الروابط مع مستودعات الكود وبناء قالب التوثيق.
محفز التشغيل (Trigger): إضافة وتأكيد تحديثات في مستودع GitHub (Push to main).

خطوات العمل (الآلية)

تفعيل Webhook في GitHub ليقوم بإرسال إشعار لمنصة n8n عند كل عملية Push جديدة لفرع Main.
مقارنة التغييرات (Diff) لتحديد الملفات والدوال البرمجية التي تم تعديلها أو إضافتها.
استخراج التعليقات البرمجية (Docstrings / Comments) من الأسطر المعدلة.
توجيه التعليقات والأكواد لنموذج Ollama مع تعليمة بإنشاء وثيقة مرجعية منسقة بصيغة Markdown تشرح المدخلات، المخرجات، والوظيفة.
إيداع (Commit) الملفات التوثيقية الناتجة إلى مجلد/فرع التوثيقات docs/.
إطلاق أمر إعادة بناء (Rebuild) لموقع Docusaurus لنشر التحديثات للجمهور.
إرسال إشعار تليجرام لمدير المشروع أو الكاتب التقني لإحاطته علماً بالتحديث.

الخلاصة

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