مشروع Bokeh

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

ملخص المشروع

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

وصف المشروع

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

1- تجريدي

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

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

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

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

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

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

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

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

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

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

مثال:

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

3. الأهداف

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

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

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

سأضمن ذلك من خلال منهجين:

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

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

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

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

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

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

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

هناك المزيد من النقاشات التي تتم حول Bokeh على منصات تابعة لجهات خارجية. وتستخدم كثير من هذه الأنظمة الأساسية بيانات وصفية مثل 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). ولن يتمّ استخدام البيانات الوصفية التي يتمّ إنشاؤها تلقائيًا إلّا كإجراء احتياطي في حال عدم توفّر بيانات تمّ إدخالها يدويًا.

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

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

4- مواد العرض

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

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

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

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

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

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

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

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

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

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

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

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

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

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

الأسبوع 4، من 10/05 إلى 10/11:

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

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

  • إعداد جلسة أسئلة وأجوبة مع المساهمين في سلسلة Bokeh حول Slack لمناقشة إرشادات النمط والتحسينات على الوثائق السردية وسير عمل العلاقات العامة/CI
  • بدء تطوير المفهوم الحالي لإثبات جدوى البيانات الوصفية لـ 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
  • حدِّث "دليل المطوِّر" وانشره ليتضمن إرشادات النمط وإضافات لسير العمل للعلاقات العامة ومسؤول التعامل مع العملاء.

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

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

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

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

مرحلة وضع اللمسات الأخيرة على المشروع

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

  • إنهاء وتقديم تقرير المشروع

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

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

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

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

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. يعد موقع presseبوابة.de أحد أكبر موزّعي البيانات الصحفية وإعلانات عن علاقات المستثمرين في ألمانيا. على سبيل المثال، تستخدم جميع أقسام الشرطة والإطفاء هذه الخدمة تقريبًا لتوزيع بياناتها الصحفية. بعد استخدام واجهة برمجة التطبيقات لسنوات عديدة كصحافية، قررت أن أطور واجهة بايثون للوصول إلى موارد بيانات الموقع الشاملة مثل كائنات بايثون. لقد كتبت الرمز والمستندات المستندة إلى Sphinx بالكامل.