معايير جودة التوثيق
يحدد هذا الدليل معايير الكتابة والصيانة لوثائق AuroraSOC.
هدف الجودة
يجب أن تكون كل صفحة مفيدة لـ:
- مبتدئ يحتاج إلى إنجاز المهمة بأمان
- محترف يحتاج إلى العمق والدقة وتفاصيل التنفيذ
نموذج الكتابة (طبقات حسب العمق)
يجب أن تتضمن كل صفحة رئيسية هذه الطبقات بالترتيب:
- ملخص باللغة البسيطة
- سير العمل خطوة بخطوة
- التفاصيل والقيود المتقدمة
- أوضاع الفشل واستكشاف الأخطاء وإصلاحها
- الصفحات ذات الصلة والخطوات التالية
أقسام الصفحة المطلوبة
بالنسبة لصفحات الإعداد والهندسة والتكامل، قم بتضمين كل ما يلي:
- متى تستخدم هذه الصفحة
- المتطلبات الأساسية
- شرح المسار الطبيعي (Happy Path)
- قائمة التحقق
- أوضاع الفشل الشائعة
- روابط لمراجع أعمق
قواعد الدقة
- تفضيل الحقائق المرتبطة بالمصدر على الذاكرة.
- تجنب الأعداد الثابتة التي لا معنى لها ما لم يتم اختبارها أو إنشاؤها.
- احتفظ بمصدر أساسي واحد لكل عائلة حقائق:
- إصدارات وقت التشغيل:
pyproject.toml،dashboard/package.json،docs/package.json - الوكلاء والمنافذ:
aurorasoc/agents/factory.py،aurorasoc/config/settings.py - سلوك واجهة برمجة التطبيقات: FastAPI OpenAPI وعمليات التنفيذ
- إصدارات وقت التشغيل:
قواعد اللغة
- استخدم لغة عربية مباشرة وواضحة أولًا.
- حدد مصطلحات المجال قبل استخدام الاختصارات.
- استخدم مصطلحات متسقة لنفس المفهوم عبر الصفحات.
- اجعل الأمثلة واقعية وقابلة للتشغيل.
- اشرح لماذا، وليس فقط ماذا.
أمثلة على التعليمات البرمجية والأوامر
- يجب أن تعمل الأوامر كما هو مكتوب على Linux.
- قم بتضمين سياق لمكان تشغيل الأوامر.
- تجنب إخراج العنصر النائب ما لم يتم تصنيفه بوضوح.
- تفضل أوامر النسخ الآمن.
قائمة التحقق من تجربة المبتدئين
- هل يمكن للمستخدم لأول مرة إكمال الصفحة دون مساعدة خارجية؟
- هل هناك مثال واحد على الأقل من النهاية إلى النهاية؟
- هل يتم ذكر النتائج المتوقعة بعد كل خطوة رئيسية؟
- هل يتم توفير استكشاف الأخطاء وإصلاحها لحالات الفشل الكبرى؟
قائمة مراجعة الخبرة المهنية
- هل الافتراضات واضحة؟
- هل تم شرح المقايضات والقيود؟
- هل تم استدعاء التبعات الأمنية؟
- هل تم توثيق مسارات المراقبة والتحقق؟
تعريف تم لـ Docs PRs
يكتمل طلب سحب المستندات عندما:
- يتم التحقق من صحة الحقائق ضد التعليمات البرمجية.
- الروابط الداخلية صالحة.
- تتبع الصفحة بنية الطبقات.
- تم تضمين مسار تحقق واحد على الأقل.
- ينجح البناء عبر فحوصات الروابط الصارمة.
معيار المراجعة
سجل كل صفحة من 1 إلى 5:
- صحة
- الوضوح
- الاكتمال
- القابلية للتنفيذ
- قابلية الصيانة
يجب تحسين أي فئة أقل من 4 قبل الدمج.