نموذج إرشادي: فريق توثيق منتج برمجي يبني نظام محتوى Git-first مع AI Assistant

تفاصيل السيناريو

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

نموذج إرشادي تكميلي لفريق توثيق برمجي ينتقل من Notion + Intercom إلى stack Git-first (Markdown + MkDocs + Outline) مع مساعد AI داخلي. تركيز على version control + AI search.

توصيف المشكلة

فريق توثيق في شركة برمجية ينقسم على ثلاثة أنظمة: مسوّدات في Notion، نشر على docs.example.com (Hugo)، أسئلة عملاء في Intercom. التحديثات تتأخر بأيام بين النظم. الفريق التقني يطلب تغييرات في الوثائق عبر Slack، لا يحدث pull request للوثائق رغم أنها في Git. النتيجة: وثائق متأخرة عن الكود، تذاكر دعم تتراكم.

الأدوات المستخدمة

• outline: أداة مستخدمة في سير العمل.
• mkdocs: أداة مستخدمة في سير العمل.
• ollama: أداة مستخدمة في سير العمل.
• open-webui: أداة مستخدمة في سير العمل.
• chatwoot: أداة مستخدمة في سير العمل.
• n8n: أداة مستخدمة في سير العمل.
• coolify: أداة مستخدمة في سير العمل.
• qdrant: أداة مستخدمة في سير العمل.

مسار العمل (Workflow)

هجرة كاملة لنظام Git-first: • كل الوثائق في monorepo (docs/ كمجلد) • محرر Outline self-hosted للكتّاب (واجهة WYSIWYG، يحفظ كـ Markdown في الخلفية) • Sync Outline ↔ Git repo (workflow n8n) • MkDocs Material للنشر العام (يبني من repo تلقائياً) • Open WebUI + Ollama + RAG على repo للـ AI Assistant • Chatwoot لاستبدال Intercom، مع تكامل AI suggestions من docs النتيجة: الكتاب يستمتعون بـ Outline، المهندسون يتعاملون مع Git، AI يجيب من docs مباشرة، وكلاء الدعم يحصلون على اقتراحات من نفس المصدر.

النتائج والفرق في الأداء

• قبل التطبيق:
• بعد التطبيق:

التكلفة التقديرية

الدروس المستفادة

• الـ resistance الأكبر من المهندسين الأصغر سناً (لم يستخدموا Markdown قبل) — كانوا يحبون Notion
• الحل: ورشات تدريبية، نشر دليل سريع • Git-first يجبر الانضباط — لا ‘صفحة مسوّدة عشوائية’، كل تعديل commit واضح
• هذا ضرر مفيد • Outline أنقذ الفريق التوثيقي من Markdown مباشر — لو طلبت منهم كتابة في VS Code لاستقالوا • RAG على docs النص فقط ليس كافٍ — الـ code examples مهمة جداً، احتجت parser خاص لها • Chatwoot suggestions أصبحت محبوبة عند الوكلاء بعد شهر، رفضوا في البداية (‘أنا أعرف أكثر’) • تكامل Slack الذي بنيناه عبر Matrix bridge لم يستخدم بالشكل المتوقع — المهندسون لا يزالون يفضّلون فتح PR مباشرة بدلاً من الـ bot • أكثر سؤال متكرر اكتشف فجوة في docs — كان عن feature موجود لكنه غير موثّق
• سيناريو مفيد للقياس المستمر • بعد سنة، docs PRs أصبحت من ضمن الـ CI/CD checklist — لا يُغلَق PR كود بدون فحص هل docs تحتاج تحديثاً • أصبح Outline هو ‘Notion’ داخلياً للجميع، حتى الفرق غير التوثيقية — قد ننقل المنظمة كلها له لاحقاً