هل منظومة التوثيق جاهزة للإنتاج؟ سجل قرار go/no-go

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

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

ابدأ بسجل قرار من صفحة واحدة

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

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

البوابة 1: ملكية المحتوى وقابليته للنقل

سمِّ المصدر المعتمد: commit في Git أو لقطة قاعدة بيانات أو حزمة تصدير. كلمة "المحرر" ليست دقيقة. حدد من يفوز إذا اختلفت الصفحة المرئية وملف Markdown والنسخة المنشورة.

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

البوابة 2: الهوية والأدوار والمحتوى الخاص

اختبر كل وضع وصول: عام، مساحة عمل، قارئ مدعو، معاينة، وإدارة. استخدم متصفحاً مجهولاً وعضواً عادياً ومديراً. يجب ألا تظهر الصفحة الخاصة في البحث أو sitemap أو Markdown أو استجابة AI أو cache عام أو وكيل الأصول.

اختبر انتهاء الدعوة وإزالة العضو وتغيير الدور وإبطال الجلسة. افتح الروابط مباشرة؛ إخفاء عنصر التنقل لا يحمي المحتوى. ولا تضع رموز إنتاج أو معرفات عملاء في سجل القرار.

البوابة 3: هوية الإصدار وضبط التغيير

احتفظ بهوية لا تتغير: Git SHA للموقع الثابت، وdigest للصورة، ومعرف نشر للخدمة المُدارة. ثم أثبت من الخارج أن هذه الهوية هي التي تخدم الزوار. نجاح CI يثبت المرشح، لا ما يعمل الآن.

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

البوابة 4: الترحيل والتراجع

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

قد تصبح العودة غير آمنة بعد كتابة بيانات جديدة. سجّل النقطة التي يحدث عندها ذلك وخطة الإصلاح الأمامي. لا تعتبر "استعادة النسخة" خطة قبل قياس زمنها ونافذة فقد البيانات والتحقق من النتائج.

البوابة 5: الصحة والمراقبة والتنبيه

افصل liveness عن readiness. قد تكون العملية حية بينما قاعدة البيانات غير متاحة. راقب المسار الكامل: DNS وTLS والوكيل والتطبيق وقاعدة البيانات والذاكرة والتخزين والبحث.

جرّب وصول التنبيه إلى إنسان في ساعات الخدمة. لوحة بلا تسليم مثبت تظل مجهولة. احتفظ بمعرف طلب في السجلات، واستبعد الأسرار وأجسام الصفحات والبيانات الشخصية غير اللازمة.

البوابة 6: النسخ الاحتياطي والاستعادة

لا تصبح النسخة الاحتياطية مثبتة إلا بعد استعادتها. استعد إلى وجهة معزولة، وافحص أعداد السجلات والأصول، وافتح صفحات ممثلة، وأعد بناء البحث. دوّن نقطة الاستعادة والزمن المقاسين بدلاً من إعلان RPO أو RTO غير مجرب.

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

البوابة 7: البحث واسترجاع AI

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

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

البوابة 8: الأداء والسعة

اختبر المسار العام على هاتف وسطح مكتب، وصفحات طويلة وكثيفة الشيفرة والصور والبحث والتنقل. سمِّ القياس المختبري synthetic، وافصل بينه وبين بيانات المستخدمين الفعلية.

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

البوابة 9: البيانات الوصفية والاكتشاف والعرض

لكل صفحة قابلة للفهرسة، تحقق من canonical واحد وعنوان ووصف ولغة واتجاه وhreflang متبادل. يجب ألا تدخل صفحات noindex إلى sitemap. افحص التحويلات، ثم اعرض الصفحة فعلياً على الهاتف وسطح المكتب.

لطلبات الآلة تحقق من content type والتفاوض وalias لـMarkdown وروابط التعافي. نفذ الاختبار دون credentials حتى لا تجعل جلسة داخلية endpoint خاصاً يبدو عاماً.

البوابة 10: الدعم ونهاية العمر والحدود القانونية

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

في نشر AGPL، وثّق كيف سيلتزم الفريق بالرخصة وفق تعديله وتقديمه للخدمة عبر الشبكة. افصل التزامات حقوق النشر عن الاسم والشعار والنطاق ومسائل العلامة التجارية. اطلب مراجعة مستشار مؤهل لما يهم المؤسسة؛ هذا الدليل تشغيلي وليس نصيحة قانونية ولا يمنح حقوق علامة.

متى يكون خيار آخر أفضل؟

يكون Docusaurus أو Starlight غالباً أبسط عندما يملك المهندسون كل التغييرات ويكون Git حد المراجعة. قد يكون GitBook أفضل عندما تكون الكتابة التعاونية المُدارة أهم من التشغيل الذاتي. يناسب Mintlify فرق توثيق المطورين التي تعتمد Git. الملاءمة التنظيمية جزء من الجاهزية.

تطبيق السجل على Nibleaf

يوفر مصدر Nibleaf أدواراً ولقطات نشر وتصدير Markdown وملفات اكتشاف وبحث Orama ومسار تثبيت ذاتي. لكن المصدر والصورة العامة ليسا الهوية نفسها. يجب أن يذكر السجل commit أو digest، وأن يختبر PostgreSQL والذاكرة والتخزين والوكيل والنطاق والبحث كما شُغّلت فعلاً.

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

المراجع وتاريخ المراجعة

رُوجعت المراجع في 2026-09-03: إرشادات Google لنقل المواقع، OWASP ASVS، إرشادات Docker Compose للإنتاج، Docusaurus، وStarlight.

إذا بقي صف حرج مجهولاً، فالقرار الصادق هو "ليس بعد"، ثم أصغر تجربة تغلق ذلك المجهول.