التوثيق الواضح هو ما يفصل التحليل لمرة واحدة عن أصل قابل لإعادة الاستخدام وجدير بالثقة. يغطي هذا الدرس القوالب والمفردات الرئيسية لكتابة تقارير التحليل وقواميس البيانات وبطاقات النماذج وتوثيق التجارب.
| القسم |
الغرض |
الطول |
| 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;
- الملخصات التنفيذية أولاً — ابدأ بالنتائج وليس المنهجية
- قواميس البيانات تمنع سوء التفسير — وثّق كل حقل
- بطاقات النماذج ليست اختيارية — ضرورية للذكاء الاصطناعي المسؤول
- وثّق التجارب بالكامل — الفرضية والنتائج والقرار
- علّق على لماذا وليس ماذا — قواعد العمل أهم من الصياغة
تهانينا على إكمال الدورة! أجب على الاختبار النهائي لاختبار معرفتك.
:::
