مشروع Bokeh

تحتوي هذه الصفحة على تفاصيل مشروع كتابة فنية تم قبوله في "موسم مستندات Google".

ملخّص المشروع

مؤسسة مفتوحة المصدر:
تأثير "موهبة"
الكاتب الفني:
vis_verborum
اسم المشروع:
إنشاء مستندات Bokeh وقراءتها ومشاركتها: تحسين مستندات Bokeh
طول المشروع:
مدة زمنية عادية (3 أشهر)

وصف المشروع

إنشاء وقراءة ومشاركة: تحسين مستندات Bokeh

1. ملخص

Bokeh هي أداة فعّالة للغاية لإنشاء رسوم بيانية تفاعلية مستندة إلى المتصفّح باستخدام Python. وتضم قاعدة مستخدمين كبيرة (502 ألف عملية تنزيل لـ conda شهريًا و855 ألف عملية تنزيل لـ PyPi) وعددًا كبيرًا من المساهمين (455 مساهمًا على GitHub). وليس من المفاجئ أنّ هناك العديد من المستندات المكثّفة التي طوّرتها Bokeh. وبالتالي، في بعض الأماكن، تكون غير متّسقة ويصعب الوصول إليها وتكون معقّدة.

يوفّر "موسم المستندات" من Google فرصة فريدة لمراجعة وتعديل بنية مستندات Bokeh ومحتوياتها بشكل مركز، والتأكّد من أنّ المستندات والأدوات وعمليات سير العمل المرتبطة بها مناسبة للمستقبل.

عملت على ترميز وتوثيق مشاريع مفتوحة المصدر باستخدام Python وSphinx (مؤخرًا: PyZillow وPyPresseportal). ما يجعلني مشاركًا فريدًا في "موسم مستندات Google" هو خبرتي في مجال الصحافة: عملت في غرف الأخبار لأكثر من 13 عامًا، وشغلت منصب رئيس تحرير لعدة سنوات وكنت من المدافعين عن التغيير الرقمي. بالإضافة إلى واجباتي الصحافية، كانت لديّ مسؤوليات متزايدة عن تصميم وتوثيق أدوات رقمية جديدة وأدلة أسلوبية، بالإضافة إلى تدريب موظفي غرف الأخبار.

بعد انتقالي مؤخرًا من أوروبا إلى الولايات المتحدة، قررت البحث عن طرق جديدة للجمع بين شغفي بالتواصل والترميز. لقد وجدت أن الكتابة التقنية هي مزيج مثالي من مهاراتي وخبراتي في الكتابة والتكنولوجيا. وفي هذا الاقتراح، سأوضّح كيف سأستخدم موسم المستندات من Google لتحسين مستندات Bokeh: من خلال تسهيل إنشاء المستندات والمساهمة فيها، وتسهيل قراءة المستندات وتسهيل مشاركة المعلومات في المستندات مع الآخرين.

2. الوضع الحالي

تتألف المستندات الرسمية لـ Bokeh من الوحدات الرئيسية التالية:

  • المستندات السردية: دليل التثبيت، دليل المستخدم، دليل المطوّرين، ملاحظات الإصدار
  • معرض العروض التوضيحية (أمثلة تفاعلية مع رمزها المصدر)
  • الدليل المرجعي (مستندات مستندة إلى سلاسل النصوص البرمجية)
  • برنامج تعليمي (مجموعة واسعة من دفاتر ملاحظات Jupyter، مستضافة على mybinder.org)
  • سلاسل النصوص البرمجية ومساعدة النماذج لبيئات التطوير المُدمَجة
  • الأمثلة وملفات README في مستودع المشروع

بالإضافة إلى ذلك، تتوفّر مجموعة كبيرة من المعلومات في منتدى دعم Bokeh وعلى Stack Overflow، حيث يجيب مطوّرو Bokeh بنشاط عن أسئلة المستخدمين، بالإضافة إلى مدوّنة Bokeh على Medium.

يتم إنشاء معظم صفحات الويب الخاصة بالمستندات باستخدام Sphinx، وذلك باستخدام العديد من إضافات Sphinx العادية والمخصّصة. على سبيل المثال، يتم إنشاء الدليل المرجعي من سلسلة توثيق باستخدام إضافات، مثل "autodoc" و"bokeh_autodoc"، وهو يشمل كثرة وتناقضات، كما هي الحال مع طبيعة التوثيق الأصلي.

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

على سبيل المثال:

الصفحة المقصودة للمستندات في Bokeh قصيرة إلى حدٍ ما ولا تتضمّن معلومات عن جميع المراجع المتاحة (لا يُشار إلى المكتبة الواسعة من مستندات وصف الدوالّ ووظائف المساعدة في النماذج أو منتديات الدعم أو العروض التوضيحية أو مدوّنة Medium). ويصعّب ذلك أيضًا على المستخدمين الجدد بدء استخدام ميزة "تأثير التمويه".

3- الأهداف

للاستفادة من مرحلة تطوير المستند التي تبلغ مدتها أحد عشر أسبوعًا بأكبر قدر ممكن من الكفاءة، سأركّز على ثلاثة عناصر رئيسية:

3.1. تحسين إنشاء المستندات

يكتب المساهمون معظم مستندات Bokeh، ويضيفون هذه المستندات كجزء من طلبات سحب الوظائف الجديدة وإصلاح الأخطاء. على الرغم من أنّني سأستخدم بعضًا من مرحلة تطوير المستندات لتعديل المستندات الحالية وإعادة تنظيمها، سأركّز على جعل سير العمل لإنشاء المستندات والحفاظ عليها متوافقًا مع المتطلبات المستقبلية: يجب أن يكون من السهل على المساهمين الحفاظ على مستوى عالٍ من الوثائق بشكلٍ ثابت.

سأحرص على ذلك من خلال طريقتَين:

  • سأقوم بإنشاء مجموعة من إرشادات الأنماط العملية والبسيطة لتضمينها في دليل المطوِّرين الحالي. ستتناول هذه الإرشادات الأسلوب والقواعد النحوية والبنية. بالإضافة إلى ذلك، سأستخدم قنوات التواصل الداخلي، مثل Slack، للتأكّد من أنّ المساهمين في Bokeh على دراية بإرشادات التصميم. سأقدّم أيضًا جلسات تدريبية فردية وجلسات أسئلة وأجوبة للفريق.
  • سأعمل مع الفريق الأساسي للعثور على مجموعة مثالية من الأدوات للتحكّم في جودة المستندات، والتي ستتم إضافتها إلى سير العمل الحالية في Bokeh لطلبات الربط (PR) والدمج المستمر (CI). استنادًا إلى متطلبات الفريق، قد يعني ذلك إضافة أدوات مثل pydocstyle أو proselint أو sphinxcontrib-spelling للتدقيق الإملائي إلى مجموعة اختبارات Bokeh أو إعداد النشر المُسبَق أو إجراءات GitHub. لقد أضفت دليلاً عمليًا على مبدأ عمل ميزة "إجراءات GitHub" في أحد مشاريعي مفتوحة المصدر.

3.2. تحسين قراءة المستندات

إنّ الهدف من المستندات الجيدة هو تسهيل العثور على المعلومات الصحيحة على المستخدمين الحاليين والمحتملين، واستخدام هذه المعلومات بأكبر قدر ممكن من الكفاءة.

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

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

تمامًا كما هو الحال مع تحسين إنشاء المستندات الموضّحة أعلاه، سأركّز على وضع أساس للتحسينات المستقبلية والمعايير العالية باستمرار لمستندات Bokeh.

3.3. تحسين مشاركة المستندات

يزداد عدد المناقشات حول Bokeh على المنصات التابعة لجهات خارجية. وتستخدم العديد من هذه المنصات البيانات الوصفية، مثل OpenGraph من Facebook، لتضمين معاينات غنية للروابط. تُستخدَم OpenGraph من قِبل خدمات مثل Facebook وTwitter وLinkedIn وSlack وiMessage. يستخدم منتدى Discourse في Bokeh أيضًا OpenGraph لعرض معاينات الروابط.

للاستفادة من هذه التكنولوجيا، سأضيف بيانات وصفية إلى صفحات الويب التي تم إنشاؤها من خلال Sphinx في تطبيق Bokeh على النحو الموضّح في المشكلة #9792. وأفضل طريقة هي استخدام إضافة Sphinx مخصّصة. قبل بضعة أيام، تم نشر أوّل إصدار من إضافة Sphinx لبيانات OpenGraph على GitHub. سأستخدم بعض مرحلة تطوير المستندات للمساعدة في تحسين هذه الإضافة لاستخدامها مع مستندات Bokeh.

لقد أنشأتُ أيضًا دليل إثبات على إمكانية تنفيذ الفكرة، وأستخدمه بنجاح في أحد مشاريعي المفتوحة المصدر، وهو PyPresseportal. تجمع هذه الإضافة تلقائيًا المعلومات ذات الصلة مثل العنوان والوصف والصورة وعنوان URL. بعد ذلك، يتم إدراج هذه المعلومات في رمز HTML الذي ينشئه Sphinx كعلامات OpenGraph.

تتمثل الخطوة التالية في تطوير هذه الإضافة في تقديم توجيهات مخصّصة لتحديد بيانات OpenGraph الوصفية يدويًا (على غرار توجيهات "meta" الحالية في docutil). ولن يتم استخدام البيانات الوصفية التي يتم إنشاؤها تلقائيًا إلا كحل احتياطي، في حال عدم توفّر بيانات تم إدخالها يدويًا.

إنّ إتاحة البيانات المنظَّمة أكثر تعقيدًا، لذا سأركّز في المقام الأول على تضمين بيانات وصفية عالية الجودة من OpenGraph لمستندات Bokeh. إنّ كل العمل الذي يتم إنجازه لدعم OpenGraph سيضع في الوقت نفسه الأسس لدعم البيانات المنظَّمة.

أبدى أعضاء في مجتمعَي Sphinx وReadTheDocs اهتمامًا بتطوير إضافات لـ OpenGraph والبيانات المنظَّمة (في المشكلتَين ‎#1758 و‎#5208، على سبيل المثال)، وسأحرص على العمل معهم عن كثب.

4. مواد العرض

باختصار، في ما يلي النتائج التي أتوقع أن أخرجها من موسم المستندات:

  • إرشادات حول أسلوب المستندات لمُسهمِعي Bokeh
  • تم تعديل سير عمل طلبَي الحصول على المراجعة والتكامل لتشملا التحكّم الآلي في جودة المستندات.
  • دليل المستخدم المعدَّل والمُعاد تنظيمه
  • الصفحة المقصودة للمستندات المعدَّلة
  • بيانات OpenGraph الوصفية المضمّنة في صفحات الويب الخاصة بالوثائق وإضافة Sphinx صالحة

بالإضافة إلى ذلك، سأحتفظ بـ "مستند سجلّ" لتوثيق رحلتي خلال "موسم المستندات" من Google على موقعي الإلكتروني الشخصي/Medium أو مدوّنة Bokeh على Medium. وسيشكّل ذلك أيضًا أساسًا لتقرير المشروع الذي سيتم إرساله إلى Google. سأُجري كل العمل بشفافية، في شكل مشاكل على GitHub وطلبات سحب، كلما أمكن ذلك.

5- المخطط الزمني

قبل مرحلة الترابط بين أفراد المنتدى: أنا أشاركُ بشكل نشِط في عدة مناقشات حول مستودع GitHub في Bokeh، وقد تواصلتُ مع "برايان فان دي فين" و"بافيثرا إسواراموري"، وهما مرشدو "بوكيه" في موسم المستندات من Google. سأبقى نشطًا في المحادثة حول Bokeh، وسأتعرّف أيضًا على Bokeh من خلال إنشاء الرسومات البيانية ونشرها.

مرحلة التفاعل مع المنتدى (من 17 آب (أغسطس) إلى 13 أيلول (سبتمبر)):

  • التعرف على الفريق الأساسي، وتحسين خطة المشروع في مقابل الموجهين
  • إعداد جدول زمني وقنوات اتصال لإعداد التقارير وتقديم الملاحظات بشكل منتظم مع المرشدين
  • أن تكون نشطًا على Slack في Bokeh لإعلام جميع المساهمين المهتمين في Bokeh بموسم المستندات من Google وأهداف مرحلة تطوير المستندات
  • جمع الملاحظات من المساهمين في Bokeh لتحسين خطة مرحلة تطوير المستند

مرحلة تطوير المستند

الأسبوع 1، من 14 إلى 20 أيلول (سبتمبر):

  • بدء تدقيق المستندات السردية وتعديلها
  • بدء صياغة إرشادات الأسلوب

الأسبوع 2، 21/09 - 09/27:

  • مواصلة العمل على إرشادات الأسلوب
  • مواصلة تعديل المستندات القصصية
  • بدء عملية إعادة هيكلة الصفحة المقصودة للمستندات

الأسبوع 3، من 28 أيلول (سبتمبر) إلى 4 تشرين الأول (أكتوبر):

  • وضع اللمسات الأخيرة على إرشادات الأسلوب
  • الانتهاء من الصفحة المقصودة للمستندات

الأسبوع 4، من 5 تشرين الأول (أكتوبر) إلى 11 تشرين الأول (أكتوبر):

  • إنهاء تعديل الوثائق القصصية
  • مناقشة مع الفريق الأساسي في Bokeh بشأن دمج أدوات التحكّم في جودة المستندات في سير عمل العلاقات العامة/التكامل المستمر

الأسبوع 5، من 12 إلى 18 تشرين الأول (أكتوبر):

  • إعداد جلسة أسئلة وأجوبة مع المساهمين في Bokeh على Slack لمناقشة إرشادات الأسلوب والتحسينات على الوثائق السردية وسير عمل العلاقات العامة/التكامل المستمر
  • بدء تطوير النموذج الحالي لإثبات مفهوم البيانات الوصفية OpenGraph إلى إضافة Sphinx قابلة للنشر
  • مراجعة إرشادات الأسلوب استنادًا إلى الملاحظات من جلسة أسئلة وأجوبة مع المساهمين في Bokeh

الأسبوع 6، من 19 إلى 25 تشرين الأول (أكتوبر):

  • بدء اختبار أدوات التحكّم في جودة المستندات في سير عمل العلاقات العامة وإدارة التغيير
  • مواصلة تطوير إضافة Sphinx للبيانات الوصفية

الأسبوع 7، من 26 تشرين الأول (أكتوبر) إلى 1 تشرين الثاني (نوفمبر):

  • اختبار إضافة Sphinx
  • جلسة أسئلة وأجوبة ثانية مع المساهمين في Bokeh على Slack
  • مراجعة المُخرَجات النهائية بناءً على الملاحظات من جلسة الأسئلة والأجوبة الثانية

الأسبوع 8، من 2 تشرين الثاني (نوفمبر) إلى 8 تشرين الثاني (نوفمبر):

  • نشر إضافة Sphinx ونشر الصفحة المقصودة المحسّنة للمستندات والسرد

الأسبوع 9، 11/09 - 11/15:

  • نشر أدوات التحكّم في جودة المستندات في سير عمل العلاقات العامة وإدارة التغيير
  • تعديل دليل المطوّرين ونشره لتضمين إرشادات حول الأسلوب وإضافة سير عمل العلاقات العامة وإدارة الإصدارات

الأسبوع 10، من 16 إلى 22 تشرين الثاني (نوفمبر):

  • إنهاء المهام المتبقية

الأسبوع 11، من 23 تشرين الثاني (نوفمبر) إلى 29 تشرين الثاني (نوفمبر):

  • بدء كتابة تقرير المشروع
  • بدء كتابة تقييم المشروع

مرحلة إنهاء المشروع

الأسبوع 12، من 30 تشرين الثاني (نوفمبر) إلى 5 كانون الأول (ديسمبر):

  • وضع اللمسات الأخيرة على تقرير المشروع وإرساله

الأسبوع 13، من 3/12 إلى 10/12:

  • إكمال تقييم المشروع وإرساله

بعد انتهاء "موسم "مستندات Google":

  • آمل أن أظلّ مشاركًا في تطوير Bokeh وأن أواصل العمل على مستندات Bokeh.
  • أخطّط لمواصلة تطوير إضافة Sphinx للبيانات الوصفية OpenGraph/البيانات المنظَّمة.
  • آمل أن أستخدم خلفيتي في الصحافة وشبكتي الحالية للترويج لـ Bokeh كأداة في صحافة البيانات. على سبيل المثال، من خلال الكتابة عن ميزة Bokeh مع مراعاة جمهور صحفي أو من خلال تقديم محادثات في المؤتمرات حول استخدام ميزة Bokeh في الإعدادات الصحفية.

6- لمحة عني

أنا صحفي من الأساس، ولديّ خبرة في الأخبار التلفزيونية والأخبار على الإنترنت والأخبار الإذاعية. من خلال عملي كمحرِّر إداري ومراسل في الأخبار التلفزيونية والرقمية، اكتسبت خبرة طويلة في الكتابة والتعديل. وفي الوقت نفسه، عملت على العديد من المشاريع التي تروّج للتحوّل الرقمي والأتمتة. لقد كتبت العديد من الأدلة التي تتناول الأدوات الرقمية ومسارات العمل، بالإضافة إلى أدلة الأسلوب واستراتيجيات التواصل لعلامات الأخبار الرقمية. قمت أيضًا بتدريب أعضاء الفريق على استخدام هذه الأدوات.

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

إنّ الأدلة والمستندات التي كتبتها في وظيفتي السابقة غير متاحة للجميع. لذلك، أركز حاليًا على المشاركة بشكل أكبر في المشاريع ذات المصدر المفتوح (يمكنك الاطّلاع أدناه على أمثلة). لقد أُنشئت عملي في إطار الكتابة التقنية استنادًا إلى أدلة الأسلوب مثل دليل أسلوب مستندات المطوّرين من Google ودليل التنسيق من Microsoft. أستخدمُ بانتظام GitHub وSlack وLinux. كنت أكتب مستندات سردية، بالإضافة إلى سلاسل توثيق وتلميحات في الكتابة، باستخدام أدوات مثل Sphinx وMypy وSphinx Autodoc.

أعمل حاليًا كمستقل. يقدّم جدولي الزمني المرونة اللازمة للعمل على مستندات Bokeh لمدة 25 ساعة تقريبًا في الأسبوع خلال مرحلة تطوير المستندات. أعمل في المنطقة الزمنية للمحيط الهادئ، ولكن يسعدني أن أتوافق مع جداول الفريق واحتياجاته.

7- أمثلة على أحدث مستندات المصادر المفتوحة

  • PyZillow: PyZillow هو برنامج Python لتغليف واجهة برمجة تطبيقات الموقع الإلكتروني للعقارات Zillow.com. بالإضافة إلى تقديم بعض الرموز البرمجية والعمل كأحد مشرفي الرموز البرمجية، كتبت المستندات الكاملة. لقد استخدمت Sphinx للتوثيق السردي، وكذلك كمرجع للوحدة. لقد أنشأت مرجع الوحدة باستخدام إضافة Sphinx autodoc، استنادًا إلى سلاسل وصف الدوال البرمجية التي أضفتها إلى الرمز.

  • ‫PyPresseportal: ‫PyPresseportal هي حزمة Python لواجهة برمجة تطبيقات الموقع الإلكتروني presseportal.de. الموقع الإلكتروني presseportal.de هو أحد أكبر موزّعي البيانات الصحفية وإعلانات علاقات المستثمرين في ألمانيا. على سبيل المثال، تستخدم جميع إدارات الشرطة والإطفاء تقريبًا هذه الخدمة لتوزيع البيانات الصحفية. بعد استخدام واجهة برمجة التطبيقات لسنوات عديدة كصحفي، قررت تطوير واجهة بايثون للوصول إلى موارد البيانات الشاملة لموقع الويب ككائنات بايثون. لقد كتبتُ التعليمات البرمجية والمستندات الكاملة المستندة إلى Sphinx.