يسعى المساهمون في WordPress إلى الحصول على رعاية لتحسين مستندات Gutenberg Developer Docs

بدأ مطورو WordPress Milana Cap و Jonathan Bossenger حملة لجمع التبرعات لتحسين وثائق مطوري Gutenberg. بدأت المحادثة بالأمس عندما قام Cap بالتغريد حول كيفية تجاهل التوثيق غالبًا عندما توظف الشركات مساهمين بدوام كامل للعمل على WordPress.

قال كاب: "عندما يكون مجتمعك غير قادر على تعلم برنامجك ، فلن يكون لديك مساهمون". "التوثيق والبرامج التعليمية أكثر أهمية بكثير مما يدركه الناس لمشروعات البرمجيات مفتوحة المصدر."

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

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

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

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

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

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

المشكلة مع وثائق مطور Gutenberg: إنها ليست صديقة للوافدين الجدد

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

قال Bossenger في الماضي أن WordPress جعل من السهل جدًا على أي شخص لديه قدر محدود من المعرفة بلغة PHP إنشاء مكون إضافي أو سمة بسرعة باستخدام خطافات الحركة والتصفية. كان من السهل إلقاء نظرة على الكود وفهم ما كان من المفترض القيام به.

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

"إذا كان أقرب ما توصلت إليه للعمل مع JavaScript في WordPress هو استخدام jQuery ، فإن التبديل إلى تطوير Gutenberg المستند إلى React لا يزال يتطلب بعض التعلم من جانبك."

بعد أخذ دورتين قبل أن يتمكن من بناء أي شيء للمحرر ، واحدة على React والأخرى على Gutenberg ، قال Bossenger إن كتيب Block Editor الحالي غير مكتوب للمطورين الذين ليس لديهم خبرة في React وجافا سكريبت الحديثة. وهو يعتقد أنها بحاجة إلى إعادة هيكلة لتوضيح المفاهيم الجديدة بشكل أفضل وتناسب نمط يسهل على الوافد الجديد استهلاكه. سلط الضوء على كتيب مطور البرنامج المساعد كمثال حيث تتبع الفصول هيكلًا وتستخدم مصطلحات تشبه إلى حد كبير كتابًا نصيًا ، مما يؤدي إلى تعريف القارئ ببطء بمفاهيم جديدة.

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

بوسنجر ليس وحده في رأيه في الوثائق الحالية. نشر بيتر تاسكر في Delicious Brains مؤخرًا برنامجًا تعليميًا حول إنشاء كتلة Gutenberg مخصصة. حتى بعد العمل مع React بدوام كامل خلال العام الماضي ، وجد أن مستندات محرر الكتلة الرسمية "نوعًا ما في كل مكان" ويصعب تحليلها.

بعد أن علق Cap على عدم وجود شركات ترعى العمل بدوام كامل على التوثيق ، اختبر Bossenger المياه بتغريدة يسأل عما إذا كان الاثنان قد يكونان قادرين على جمع الأموال لتحسين مستندات Gutenberg.

قال كاب: "تمامًا مثل فريق Block Editor (وأي فريق Make آخر) ، فإن فريق التوثيق يعاني من نقص في الموظفين". "لا يمكننا تحمل تكريس عدد قليل من الأعضاء للتعلم أولاً ثم كتابة الوثائق الخاصة بالتطوير باستخدام محرر الكتلة. هذا هو السبب الرئيسي لتغريدتي. سترى المساهمين المدعومين في كل مكان ولكن ليس في الوثائق وسأجرؤ على القول إن كلاهما لهما نفس القدر من الأهمية ".

قبل إطلاق حملة جمع التبرعات الخاصة بهم ، يخطط Cap and Bossenger لاستعراض الوثائق الحالية وتحديد الثغرات الواضحة وتحديد الأسئلة التي لا تزال بدون إجابة لأولئك الجدد على التطوير لمحرر الكتلة.

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

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

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