كتابة تقارير التحليل وتوثيق البيانات

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

كتابة تقارير التحليل

هيكل تقرير التحليل

القسم	الغرض	الطول
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 (المراقبة)	كيفية تتبع الأداء وجدول إعادة التدريب

توثيق التجارب واختبارات A/B

قالب توثيق التجربة

العنصر	الوصف
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 بدون أرقام تذاكر
ضمّن الوحدات والنطاقات الصالحة	اكتب تعليقات تناقض الكود
ارجع للتذاكر/التوثيق للمنطق المعقد	اكتب تعليقات أطول من الكود نفسه

مثال على تعليقات SQL

-- تصفية للطلبات المكتملة فقط (استبعاد الملغاة/المستردة)
-- قاعدة العمل: الطلب "مكتمل" عندما حالة الدفع = 'settled'
-- وحالة التنفيذ = 'delivered'
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;

النقاط الرئيسية

1. الملخصات التنفيذية أولاً — ابدأ بالنتائج وليس المنهجية
2. قواميس البيانات تمنع سوء التفسير — وثّق كل حقل
3. بطاقات النماذج ليست اختيارية — ضرورية للذكاء الاصطناعي المسؤول
4. وثّق التجارب بالكامل — الفرضية والنتائج والقرار
5. علّق على لماذا وليس ماذا — قواعد العمل أهم من الصياغة

تهانينا على إكمال الدورة! أجب على الاختبار النهائي لاختبار معرفتك.

:::