مشروع Bokeh

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

ملخص المشروع

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

وصف المشروع

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

1- تجريدي

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

يتيح موسم المستندات من Google فرصة فريدة لمراجعة ومراجعة بنية وثائق Bokeh ومحتوياتها، وكذلك للحرص على أن تكون الوثائق والأدوات ومهام سير العمل المرتبطة بها إثباتًا للمستقبل.

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

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

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

تتألف الوثائق الرسمية لـ "بوكيه" من الوحدات الرئيسية التالية:

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

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

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

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

مثال:

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

3. الأهداف

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

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

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

سأضمن ذلك بطريقتين:

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

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

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

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

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

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

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

يتم إجراء المزيد والمزيد من النقاشات حول ميزة "بوكيه" على منصات تابعة لجهات خارجية. وتستخدم العديد من هذه الأنظمة بيانات وصفية مثل الرسم البياني المفتوح (OpenGraph) في Facebook لتضمين معاينات عالية القيمة للروابط. يتم استخدام الرسم البياني المفتوح (OpenGraph) عن طريق خدمات مثل Facebook وTwitter وLinkedIn وSlack وiMessage. يستخدم منتدى Discourse في Bokeh أيضًا الرسم البياني المفتوح (OpenGraph) لعرض معاينات الروابط.

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

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

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

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

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

4. مواد العرض

باختصار، هذه هي المُخرَجات النهائية التي أتوقّع أن تظهر من Season of Docs:

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

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

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

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

مرحلة الترابط بين أفراد المنتدى (من 17/08/17 إلى 13/09/13):

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

مرحلة إعداد المستند

الأسبوع 1، 09/14 - 09/20:

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

الأسبوع الثاني، 09/21 - 09/27:

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

الأسبوع 3، 09/28 - 10/04:

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

الأسبوع 4، 10/05 - 10/11:

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

الأسبوع 5، 10/12 - 10/18:

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

الأسبوع 6، 10/19 - 10/25:

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

الأسبوع 7، 10/26 - 11/01:

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

الأسبوع 8، 11/02 - 11/08:

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

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

  • نشر أدوات مراقبة جودة المستندات في سير عمل العلاقات العامة وCI
  • عدِّل "دليل المطوِّر" وانشره لتضمين إرشادات التنسيق والإضافات المتعلقة بسير العمل والعلاقات العامة وCI.

الأسبوع 10 و11/16 و11/22:

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

الأسبوع 11 و11/23 و29/11:

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

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

الأسبوع 12، 11/30 - 12/05:

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

الأسبوع 13، 12/03 - 12/10:

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

بعد ختام ”موسم المستندات“ من Google:

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

6. لمحة عني

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

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

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

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

7. أمثلة حديثة على الوثائق المفتوحة المصدر

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

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