انتقل إلى المحتوى

تعلم كتابة درس تعليمي (tutorial) لـ NumPy

إطار عمل Diátaxis للتوثيق يقسم الدروس التعليمية، أدلة الكيفية، الشرح، والمراجع

مصدر الصورة: إطار عمل Diátaxis لدانييل بروسيدا، مرخص بموجب CC-BY-SA 4.0.

+++

ما ستفعله (What you'll do)

مسترشدًا بقالب (template)، ستكتب tutorial لـ NumPy.

ما ستتعلمه (What you'll learn)

  • ستكون قادرًا على صياغة tutorial يتبع تنسيقًا قياسيًا ويعكس ممارسة تعليمية جيدة.

  • ستتعلم العناوين القياسية الثلاثة التي تفتح tutorial لـ NumPy -- ما ستفعله، ما ستتعلمه، و ما ستحتاجه -- وبعض العناوين الاختيارية في الأسفل -- بمفردك، في الممارسة، قراءة إضافية.

  • ستعرف ما الذي يجعل ما ستتعلمه مختلفًا عن ما ستفعله.

  • ستكون قادرًا على التمييز بين tutorial و how-to.

  • ستتعلم ما لا يجب وضعه في قسم ما ستتعلمه.

ما ستحتاجه (What you'll need)

  • هذا الـ template.

  • صورة لقارئك المستهدف.

    • تمامًا كما تسرد المدارس المتطلبات الأساسية للدورات ذات المستوى الأعلى، يمكنك افتراض أن القراء يعرفون بعض الأشياء (التي يجب عليك سردها، كما هو مذكور في النقطة التالية). الشرح المفرط يعيق الـ tutorial ويحجب النقاط الرئيسية.
    • ولكن ضع نفسك أيضًا مكان القارئ وفكر فيما يجب شرحه على طول الطريق.

  • "ما ستحتاجه" هي قائمة بـ:

    • الحزم (packages) التي يجب أن تكون موجودة على جهاز المستخدم قبل أن يبدأ. لا تضمن numpy.
    • ما افترضت أن القارئ يعرفه في النقطة أعلاه. لا تقل Python؛ الإلمام بمكررات Python (familiarity with Python iterators) أمر جيد.

  • عدم الرسمية والحماس. تخيل قارئك ليس في الجمهور بل بجانبك.

  • الرغبة في كتابة جمل غير كاملة لنقاط ما ستحتاجه. لا تبدأ بكلمات "ستحتاج إلى."

  • ليس مطلوبًا مهارات اللغة الإنجليزية الأصلية. يمكن للآخرين المساعدة.

بعد خط أفقي، ابدأ عناوينك الخاصة

تبدأ خطوات الـ tutorial الخاصة بك هنا، باستخدام عناوين من اختيارك. في نهاية الـ tutorial، ستضع خطًا أفقيًا آخر وتعود إلى العناوين القياسية.

العناوين تحتوي على أفعال

بشكل عام، قم بتضمين فعل في العنوان؛ وبالتالي تعلم كتابة tutorial لـ NumPy بدلاً من "قواعد لـ tutorials NumPy." فكر في وضع أفعال في العناوين أيضًا.

العناوين تكون بأحرف صغيرة (lowercase)

قم بكتابة الحرف الأول من الكلمة الأولى بحرف كبير، وبعد ذلك فقط الكلمات التي يتم كتابتها عادةً بحرف كبير (لذلك ليس "Titles Are Lowercase").

ماذا تقول في "ما ستتعلمه"

تجنب التجريد (abstraction). "حول" هو مؤشر: بدلاً من كتابة "ستتعلم حول إدخال/إخراج NumPy (NumPy I/O)،" اكتب "ستتعلم كيفية قراءة ملف نصي محدد بفواصل (comma-delimited text file) إلى مصفوفة NumPy (NumPy array)."

لماذا يختلف "ما ستفعله" و "ما ستتعلمه"؟

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

تجنب الملاحظات الجانبية (asides)

كما أوضح خبير كتابة الوثائق دانييل بروسيدا:

لا تشرح أي شيء لا يحتاج المتعلم إلى معرفته لإكمال الـ tutorial.

نظرًا لأن خطوات الـ tutorial يتم اختيارها لتكون واضحة وسهلة، فقد لا ترقى إلى مستوى الإنتاج (production-grade). نعم، يجب عليك مشاركة هذا، ولكن ليس أثناء الـ tutorial، الذي يجب أن يكون مباشرًا ومؤكدًا. قسم In practice هو المكان المناسب للتفاصيل والاستثناءات والبدائل والملاحظات الدقيقة المماثلة.

استخدم الرسوم البيانية والرسوم التوضيحية (plots and illustrations)

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

رسم توضيحي أسفل العنوان، حتى لو كان زخرفيًا فقط، يجعل صفحتك مميزة.

استخدم مجموعات بيانات حقيقية (real datasets) عندما يكون ذلك ممكنًا

من المرجح أن ينجذب القراء إلى حالة استخدام حقيقية. تأكد من أن لديك حقوق البيانات.

الدروس التعليمية (Tutorials) وأدلة الكيفية (how-to's) -- متشابهة ولكنها مختلفة

قراء الـ tutorial هم غرباء يريدون الشعور بالمكان. اختر وجهة واحدة واشرح المعالم على طول الطريق.

على عكس قراء الـ how-to، الذين يعرفون ما يحتاجون إليه، لا يعرف قراء الـ tutorial ما لا يعرفونه. لذلك بينما تحتاج الـ tutorials إلى عناوين مثل ما ستفعله و ما ستتعلمه، فإن هذه العناوين لن تظهر أبدًا في الـ how-to.

استفد من دليل أسلوب مستندات Google (Google doc style guide)

تتبع وثائق NumPy دليل أسلوب وثائق مطوري Google. بالإضافة إلى توفير إجابات للأسئلة المتكررة ("crossreference" أو "cross-reference"؟) يمتلئ الدليل باقتراحات من شأنها تعزيز كتابة وثائقك.

يجب أن يكون دفتر الملاحظات (notebook) قابلاً للتنفيذ بالكامل

يجب أن يقوم Run all cells بتنفيذ جميع الخلايا حتى نهاية الملف. إذا كنت تعرض تعبيرًا سيئًا وتريد إظهار تتبع الخطأ (traceback)، فقم بالتعليق على التعبير وضع الـ traceback في خلية نصية.

(لاحظ أن علامات الاقتباس الخلفية الثلاثية لن تكون كافية لـ traceback يحتوي على <text inside angle brackets>، يجب استبدال الأقواس الزاوية بـ &lt; و &gt; كما هو موضح في markdown خلية النص أدناه.)

# 100/0
--------------------------------------------------------------------------- ZeroDivisionError Traceback (most recent call last) <ipython-input-10-bbe761e74a70> in <module> ----> 1 100/0 ZeroDivisionError: division by zero

+++

بمفردك (On your own)

أغلق قسم الـ tutorial بخط أفقي. أنت حر في اتخاذ أي اتجاه الآن، ولكن إليك ثلاثة أقسام مقترحة.

في قسم On your own الاختياري، يمكنك تقديم مهمة للقراء لممارسة مهاراتهم الجديدة. إذا كان سؤالًا بإجابة، فقدمها -- ربما في حاشية سفلية لمنعها من أن تكون مفسدة.

في الممارسة (In practice)...

  • التفاصيل الدقيقة التي تجنبتها يمكن أن توضع في هذا القسم.

  • لا تقل فقط إنه يتم عادة بطريقة أخرى؛ اشرح لماذا.

قراءة إضافية (Further reading)