التوثيق الواضح هو ما يفصل التحليل لمرة واحدة عن أصل قابل لإعادة الاستخدام وجدير بالثقة. يغطي هذا الدرس القوالب والمفردات الرئيسية لكتابة تقارير التحليل وقواميس البيانات وبطاقات النماذج وتوثيق التجارب.
| القسم | الغرض | الطول |
|---|
| Executive Summary (الملخص التنفيذي) | النتائج والتوصيات الرئيسية بلغة بسيطة | 3-5 جمل |
| Business Context (سياق الأعمال) | لماذا تم هذا التحليل وأي سؤال يجيب عنه | 1-2 فقرة |
| Methodology (المنهجية) | كيف تم إجراء التحليل | صفحة واحدة |
| Findings (النتائج) | النتائج التفصيلية مع الرسوم البيانية والجداول الداعمة | 2-5 صفحات |
| Recommendations (التوصيات) | إجراءات محددة بناءً على النتائج | صفحة واحدة |
| Limitations (القيود) | ما لا يغطيه التحليل والتحفظات | نصف صفحة |
| Appendix (الملحق) | البيانات الخام والرسوم الإضافية والتفاصيل التقنية | حسب الحاجة |
BACKGROUND (الخلفية):
[الفريق] طلب منا [تحليل/التحقيق في/بناء]
[ماذا] من أجل [الهدف التجاري].
KEY FINDINGS (النتائج الرئيسية):
1. [أهم نتيجة بأرقام محددة]
2. [النتيجة الثانية بأرقام محددة]
3. [النتيجة الثالثة بأرقام محددة]
RECOMMENDATION (التوصية):
بناءً على هذا التحليل، نوصي بـ [إجراء محدد].
من المتوقع أن [التأثير التجاري بأرقام].
| العبارة | متى تستخدمها |
|---|
| "This analysis examines..." (هذا التحليل يفحص...) | فتح قسم المنهجية |
| "The data reveals that..." (البيانات تكشف أن...) | تقديم نتيجة |
| "A key insight is..." (رؤية رئيسية هي...) | إبراز نتيجة مهمة |
| "Contrary to expectations..." (خلافاً للتوقعات...) | تقديم نتيجة مفاجئة |
| "One limitation is..." (أحد القيود هو...) | الاعتراف بتحفظ |
| "Based on these findings, we recommend..." (بناءً على هذه النتائج، نوصي...) | الانتقال للتوصيات |
| "Further analysis is needed..." (هناك حاجة لمزيد من التحليل...) | تحديد مجالات للعمل المستقبلي |
| المصطلح | المعنى |
|---|
| Upstream (المنبع) | نظام أو جدول يُغذي البيانات في هذا الخط |
| Downstream (المصب) | نظام أو جدول يستقبل بيانات من هذا الخط |
| Dependency (التبعية) | شيء يتطلبه هذا الخط للتشغيل بنجاح |
| Failure mode (وضع الفشل) | كيف ينكسر الخط عندما يحدث خطأ |
| Recovery procedure (إجراء الاستعادة) | خطوات الإصلاح وإعادة التشغيل بعد فشل |
| Runbook (دليل التشغيل) | دليل خطوة بخطوة لتشغيل أو استكشاف أخطاء الخط |
| اسم الحقل | نوع البيانات | الوصف | قيمة نموذجية | القيم الصالحة | قابل للفراغ؟ |
|---|
user_id | INTEGER | معرّف فريد لكل مستخدم | 12345 | أعداد صحيحة موجبة | لا |
signup_date | DATE | تاريخ إنشاء الحساب | 2025-03-15 | أي تاريخ صالح | لا |
plan_type | VARCHAR | خطة اشتراك المستخدم | "premium" | free, basic, premium | لا |
monthly_spend | DECIMAL | المبلغ المنفق في الشهر الحالي | 49.99 | 0.00 - 99999.99 | نعم |
is_active | BOOLEAN | هل سجل المستخدم دخوله خلال 30 يوماً | true | true, false | لا |
| المصطلح | المعنى |
|---|
| Nullable (قابل للفراغ) | ما إذا كان الحقل يمكن أن يحتوي قيم NULL (مفقودة) |
| Primary key (المفتاح الأساسي) | المعرّف الفريد لكل صف |
| Foreign key (المفتاح الخارجي) | حقل يشير إلى مفتاح أساسي في جدول آخر |
| Cardinality (العددية) | عدد القيم المميزة في حقل |
| Grain (الحبيبية) | مستوى التفصيل الذي يمثله كل صف |
| Business rule (قاعدة العمل) | قيد أو منطق يحدد القيم الصالحة |
بطاقات النماذج هي توثيق موحد لنماذج التعلم الآلي تعزز الشفافية والمسؤولية:
| القسم | ما يتضمنه |
|---|
| Model Details (تفاصيل النموذج) | النوع والإصدار وتاريخ التدريب والمالك |
| Intended Use (الاستخدام المقصود) | حالة الاستخدام الأساسية والمستخدمون المستهدفون والاستخدامات خارج النطاق |
| Training Data (بيانات التدريب) | مجموعة البيانات وحجمها والنطاق الزمني والميزات والتحيزات المعروفة |
| Evaluation Metrics (مقاييس التقييم) | الدقة والضبط والاستدعاء ودرجة F1 وAUC-ROC |
| Performance by Subgroup (الأداء حسب المجموعة الفرعية) | الأداء عبر مختلف الشرائح الديموغرافية |
| Limitations (القيود) | المشاكل المعروفة والحالات الحدية |
| Ethical Considerations (الاعتبارات الأخلاقية) | مخاوف التحيز ومتطلبات المراجعة البشرية |
| Monitoring (المراقبة) | كيفية تتبع الأداء وجدول إعادة التدريب |
| العنصر | الوصف |
|---|
| Hypothesis (الفرضية) | إذا [التغيير]، فإن [المقياس] سيتحسن/ينخفض بمقدار [المبلغ] لأن [المنطق] |
| Design (التصميم) | نوع الاختبار ومجموعة التحكم ومجموعة المعالجة |
| Metrics (المقاييس) | المقياس الأساسي والمقاييس الثانوية ومقاييس الحماية |
| Results (النتائج) | قيم التحكم والمعالجة والرفع والقيمة الاحتمالية والدلالة |
| Decision (القرار) | إطلاق / عدم إطلاق / تكرار |
| Learnings (الدروس المستفادة) | ما تعلمه الفريق من هذه التجربة |
"We hypothesize that simplifying the checkout flow
will increase conversion by 5%."
نفترض أن تبسيط تدفق الدفع سيزيد التحويل بنسبة 5%
"The treatment showed a 7.2% lift in conversion rate
(p = 0.003)."
أظهرت المعالجة رفعاً بنسبة 7.2% في معدل التحويل
"We recommend shipping the treatment to 100% of users."
نوصي بإطلاق المعالجة لـ 100% من المستخدمين
| افعل | لا تفعل |
|---|
| اشرح لماذا يفعل الكود شيئاً | اشرح ماذا يفعل الكود (الكود يُظهر ذلك) |
| وثّق قواعد العمل ومنطق المجال | اذكر الواضح (# increment counter by 1) |
| أشر للحالات الحدية ومعالجتها | اترك تعليقات TODO بدون أرقام تذاكر |
| ضمّن الوحدات والنطاقات الصالحة | اكتب تعليقات تناقض الكود |
| ارجع للتذاكر/التوثيق للمنطق المعقد | اكتب تعليقات أطول من الكود نفسه |
SELECT order_date, product_category,
SUM(order_total) AS daily_revenue
FROM orders
WHERE payment_status = 'settled'
AND fulfillment_status = 'delivered'
AND customer_id NOT IN (SELECT id FROM internal_test_accounts)
GROUP BY order_date, product_category;
- الملخصات التنفيذية أولاً — ابدأ بالنتائج وليس المنهجية
- قواميس البيانات تمنع سوء التفسير — وثّق كل حقل
- بطاقات النماذج ليست اختيارية — ضرورية للذكاء الاصطناعي المسؤول
- وثّق التجارب بالكامل — الفرضية والنتائج والقرار
- علّق على لماذا وليس ماذا — قواعد العمل أهم من الصياغة
تهانينا على إكمال الدورة! أجب على الاختبار النهائي لاختبار معرفتك.
:::