تحتوي هذه الصفحة على تفاصيل مشروع كتابة تقنيّة تم قبوله في موسم المستندات من Google.
ملخص المشروع
- المؤسسة المفتوحة المصدر:
- CERN-HSF
- الكاتب التقني:
- أريادن
- اسم المشروع:
- Rucio – تحديث (إعادة هيكلة وإعادة صياغة) مستندات Rucio
- مدة المشروع:
- المدة العادية (3 أشهر)
وصف المشروع
ملخص: تم تطوير إطار عمل Rucio بهدف إدارة وتنظيم كميات كبيرة من البيانات العلمية الموزعة جغرافيًا عبر مراكز البيانات غير المتجانسة. ويتميز إطار العمل هذا بإمكانياته مثل استعادة البيانات الموزَّعة والنسخ المماثل بشكل تكيُّفي، وهو قابل للتوسّع ودمج وحدات وقابل للتوسع إلى حد كبير. سيكون المستهلكون لوثائق مثل هذه الخدمة من خلفيات متنوعة ولديهم متطلبات متنوعة عند الوصول إليها. من هذا المنطلق، يجب أن تساهم المستندات الجيدة الخاصة بهذه الخدمة في تبسيط عملية اعتمادها واستخدامها للمستخدمين النهائيين، كما يجب أن تكون مرجعًا للمشاكل الشائعة وتحديد المشاكل وحلّها.
في حال عدم توفّر مثل هذه المستندات، ستواجه صعوبات كبيرة في طريق الاستخدام الفعّال والفعّال. ومن المحتمل أن يؤدي هذا إلى زيادة تكاليف الدعم ويشكّل خطرًا على السمعة على هوية الشركة للمنتج. التوثيق هو، بعد كل شيء، طريقة للتواصل. وبالتالي، فإنّ ضمان حصر التواصل ضمن إطار عمل يمكن إدارته والوصول إليه مع الحفاظ على صلته بتحديد الإصدارات المناسبة هو ضمان نجاحنا في ذلك.
في وقت كتابة هذا التقرير، تم استخدام إطار عمل Rurio لتلبية متطلبات الطاقة العالية لتجارب "أتلاس" و"نظام إدارة المحتوى" (CMS) في مصادم الهدرونات الكبير. كما يتم استخدامه أيضًا لدعم احتياجات المجتمعات العلمية المتنوعة في ما يتعلق بـ LHC، مثل الفيزياء الفلكية، مما يجعل من الضروري أن تكون المستندات ذات صلة بالموضوع وسهل الوصول إليها قدر الإمكان. بمساعدة هذا المشروع، ترغب CERN (المنظمة الأوروبية للأبحاث النووية) في تمكين المستخدمين النهائيين في روسيو من التمتع بتجربة سلسة أثناء استخدام إطار العمل من خلال توفير عرض مركزي للوصول إلى جميع الوثائق ذات الصلة.
الحالة الحالية: اعتبارًا من اليوم، تنتشر مستندات المستخدم في أماكن مختلفة وهي معروضة بتنسيقات متعددة، منها المقالات العلمية على readthedocs.io مع تضمين المصدر في الرمز البرمجي أو Google Drive أو GitHub أو DockerHub أو Wikis. تعرض المصادر المتعددة مشكلات في تتبع الإصدارات وصحة الوثائق. بالإضافة إلى ذلك، يشكّل النموذج اللامركزي للتوثيق عقبات كبيرة في التنقّل وعرض المعلومات ذات الصلة لحالة استخدام معيّنة. وعلى وجه الخصوص في حالة Wikis، قد تكون المعلومات المقدّمة في تجربة معيّنة قابلة للتطبيق بشكل كبير على حالات أخرى موجودة أيضًا في مصادر أخرى. ومع ذلك، وبسبب نقص عمليات الدمج والروابط المناسبة، تظل هذه المعلومات غير نشِطة، ومن المحتمل أن تكون غير مستغلة بشكل كافٍ.
لماذا تعد وثائق المستخدم المقترحة أفضل من الوثائق الحالية؟ بالنظر إلى المشكلة متعددة الأوجه، فإن النموذج المقترح أدناه يزيل العقبات في التنقل وتحديد الإصدارات وتتبع وعرض الوثائق كما هو مفصل أدناه:
تهدف إعادة هيكلة الوثائق إلى تبسيط الجهود المبذولة في التنقل من أجل المستخدم. فهو لا يحتاج إلى النزول أثناء البحث عن المعلومات لأنه سيتم تصنيفها أو تصنيفها لتبسيطها. ومن منظور إداري، سيكون من السهل تحديد الإصدارات والتتبُّع لأنّ عملية إعادة الهيكلة ستوفّر حرية التصنيف على أساس المتطلبات. ستكون مركزية جميع الوثائق المعاد هيكلتها ضمان أن جميع المعلومات مرئية للمستخدم دون الحاجة إلى الإشارة إلى مصادر متعددة.
التحليل: بعد قراءة موجز المتطلبات وإجراء محادثات مع الفريق الإرشادي، تكون خصوماتي للحالة الحالية لوثائق Rucio كما يلي:
هناك ستة مصادر رئيسية للوثائق: - رابط Google Drive : https://drive.google.com/drive/folders/1EEN8l1dFjDSgavPrAMMooDjEodHP7aU7
Readthedocs بدعم من Sphinx مع مصدر في التعليمة البرمجية رابط إلى الرمز: https://github.com/rucio/rucio رابط إلى Readthe Docs: https://rucio.readthedocs.io/en/latest/
DockerHub رابط: https://hub.docker.com/u/rucio
GitHub رابط: https://github.com/rucio/rucio
Wikis رابط: https://twiki.cern.ch/twiki/bin/view/AtlasComputing/AtlasDistributedComputing
رابط المقالات العلمية: https://arxiv.org/abs/1902.09857
وتتوفّر المستندات في هذه المصادر بتنسيقات مختلفة. على سبيل المثال، يحتوي Google Drive على مستندات في شكل "العروض التقديمية من Google" و"مستندات Google"، يحتوي GitHub على ملفات بشكل أساسي بلغة ترميز reOrganizationText وما إلى ذلك. ما يؤدي نقص في عمليات تحديد الإصدارات والتتبُّع إلى نشر معلومات متكررة في مصادر متعددة. لا يوجد توحيد في وضع علامات/تصنيف المعلومات. لذلك، يجب توفُّر خبرة سابقة وخبرة أثناء البحث.
نظرًا للتنسيقات والمصادر التي لا حصر لها، نتوقّع إعادة هيكلة المعلومات وجعلها مركزية باستخدام mkdocs. من أجل تحسين فهمي للأدوات، قمت بالبحث والتعرف على استخدامها.
القرار: الوثائق الحالية غير مهيكلة ومبعثرة دون الربط المناسب. كما أنه يفتقر إلى المركزية والتوحيد في التنسيق. ويؤدي ذلك إلى اضطرار المستخدمين إلى بذل جهود إضافية في عمليات البحث. تُحدث هذه الفجوات أيضًا ضغوطًا غير ضرورية على المشرفين أو مسؤولي الصيانة أو العملاء المحتملين، وبالتالي يصبح من الصعب الحفاظ على اتّباع نهج يستند إلى المنتدى لصيانة المستندات وتعديلها. تراجعت تجربة المستخدم والمساهم إلى حد كبير وستتكرر
هيكل للوثائق المقترحة:
بعد تحليل شامل للمتطلبات، قررت معالجة المشكلات الرئيسية من خلال نموذج معاد للتوثيق.
يتم عرض النموذج المُعاد الهيكلة في النموذج التجريبي المرفق أدناه وسيتم تصنيف كل جزء من الوثائق في الفئات السبع التالية:
- لمحة عامة
- البدء
- المفاهيم
- واجهات Rucio
- المهام
- البرامج التعليمية
- المعرفة المتقدّمة
وبالطبع، هناك تحسينات مثل إضافة روابط أرغب في العمل عليها بعد الانتهاء من هذا البرنامج. مع وصول أكثر من 1000 مستخدم نشط إلى 500 بيتابايت من البيانات على Rucio، ينبغي أن تكون إعادة الهيكلة المقترحة لوثائقها قادرة على تقليل حاجة المستخدمين بشكل كبير إلى اللجوء إلى القائمة البريدية للدعم. سيكون الهدف هو تحسين تجربة المستخدم عن طريق تقليل عدد النقرات وتسهيل عرض المستندات من خلال التصنيف والتصنيف. ويتوفر كل ما يمكن معرفته من منظور المستخدم/العمليات/موظفي الإدارة في غضون 3 نقرات أو أقل.
رابط النموذج التجريبي: https://drive.google.com/file/d/1vSYgOkB9s9eEr2soNs7ujMLHzDlKn_hr/view?usp=sharing)
أهداف المشروع: - تحليل وتنقيح المعلومات المتكررة المتوفرة من مصادر مختلفة. أي أن كل معلومة يجب أن يكون لها مصدر واحد للحقيقة. - إعادة التنظيم عن طريق وضع علامات على المستندات الحالية وتصنيفها إلى أجزاء مختلفة - نقل الوثائق التي أُعيد تنظيمها إلى عرض مركزي استنادًا إلى mkdocs - إعادة تنسيق/استيراد الوثائق التي لا يمكن نقلها بسبب قيود تنسيق الملف - إعداد تعديل الوثائق التي تعتمد على المنتدى لضمان سد أي فجوات مفقودة - في ما يتعلق بالارتباطات أو التحديثات على المعلومات أو تصحيح الأخطاء.
وقد وصلنا إلى جميع البنية الأساسية لهذا النظام، ومع ذلك، سيتحسّن نموذجي بناءً على النظام الحالي من خلال وضع الإرشادات المناسبة للمساهمة والإدارة مع المستندات المناسبة. علاوة على ذلك، أتصور دمج لوحات مشروع GitHub لتتبع المشكلات وصحة المشروع بشكل عام.
الجدول الزمني: - قبل 16 آب (أغسطس) --> التعرّف على الإصدارات الحالية من الوثائق وعملية Rucio--> تعلُّم أساليب جديدة ومهارات كتابة فنية ستكون مفيدة خلال مدة المشروع --> المساهمة في حل مشاكل التوثيق، إن وجدت، التي يتم الإبلاغ عنها على GitHub
الترابط بين أفراد المنتدى (17 آب (أغسطس) - 13 أيلول (سبتمبر)) --> إعداد قناة اتصال ووقت لاحتساب الفرق في المناطق الزمنية (Pune بعد 3 ساعات و30 دقيقة) --> المشكلات الرئيسية التي يجب تحديدها نحو تحسين الأهداف --> تعرَّف على مزيد من المعلومات حول المنتدى والمؤسسة وإطار العمل من خلال المشاركة في المحادثات. --> تقييم هيكل التوثيق المقترح مع الموجهين والأعضاء الرئيسيين الآخرين في المؤسسة من أجل الجدوى وإمكانية التنفيذ. --> وضع اللمسات الأخيرة على الميزات المقترحة وأي تعديلات أخرى قد يلزم إجراؤها على الوثائق الحالية.
فترة التوثيق (14 سبتمبر - 30 نوفمبر) بناءً على التنسيق المقترح الذي صياغته هنا، قمت بتقديم تفصيل للمعالم الرئيسية التي أخطط لتحقيقها خلال فترة التوثيق.
--> المعلم الرئيسي رقم 1: التصنيف والتسمية ETC: 28 أيلول (سبتمبر) 2020 سيؤدي دمج الوثائق المتاحة ووضع علامات عليها إلى تبسيط عملية إعادة الهيكلة والتقليم إلى حد كبير.
--> المعلم الرئيسي رقم 2: التحليل والتشذيب وإعادة الهيكلة ETC: 19 تشرين الأول (أكتوبر) 2020 سيتم تحليل الوثائق التي تم تصنيفها خلال المعلم الرئيسي رقم 1 بحثًا عن التكرارات + مصادر المعلومات المتكررة. كما هو مذكور في معلومات المشروع، نستهدف مصدرًا واحدًا للحقيقة لجميع المعلومات المتوفرة.
--> المعلم الرئيسي الثالث: التنسيق المركزي وإعادة التنسيق: ETC: 9 تشرين الثاني (نوفمبر) 2020 بعد الانتهاء من تنقيح المستندات وإعادة تنظيمها بشكل صحيح، أسعى إلى إعادة تنسيقها أولاً. ونظرًا لاختلاف المصادر، تختلف التنسيقات ويجب أولاً تحويلها إلى تنسيق مناسب. بمجرد الانتهاء من ذلك، ستصبح عملية التمركز أسهل.
--> المعلم الرئيسي 4: إعداد لوحات التتبّع والوثائق المتعلّقة بالحوكمة/المساهمات ETC: 23 تشرين الثاني (نوفمبر) 2020 تهدف هذه المرحلة إلى ضمان استمرار تعديل المستندات بعد اكتمال المشروع. سيؤدي وضع الإرشادات وإعداد لوحات إدارة المشروع إلى تخفيف العبء على الأعضاء الإداريين لطلب مساهمات المجتمع وتتبعها بشكل فعال.
--> تقييم المشروع (30 تشرين الثاني (نوفمبر) - 5 ديسمبر) إرسال تقرير المشروع وتقييم المعلمين كتابة وتقديم تقرير حول تجربتي كمشارك في Season of Docs.
لماذا هذا المشروع؟ أرى أنّ إكمال الرموز البرمجية بوثائق مكتوبة جيدًا ونسخة معيَّنة هي السبيل الوحيد لزيادة الاعتماد والاستخدام بشكل أفضل. وعلى الصعيد الشخصي، لقد انبهرت بالطريقة التي كانت بها المنظمة الأوروبية للأبحاث النووية (CERN) رائدة في مجال الأبحاث الحديثة في مجالات مختلفة من الفيزياء. نظرًا لحجم المعلومات التي تمت معالجتها ونقلها وإنشاؤها خلال هذه التجارب، كنت متشوقًا دائمًا بشأن كيفية إدارة البيانات للرجوع إليها واستخدامها في المستقبل داخل المؤسسة. سيكون من دواعي الشرف المساهمة في تحسين التوثيق لإطار عمل يدعم بعض الأبحاث والاكتشافات العلمية المذهلة.
لماذا أنا الشخص المناسب لهذا المشروع؟ بالإضافة إلى استيفاء المتطلبات الأساسية، أنا واثق من أنني سأكون الشخص المناسب لهذا المشروع منذ:
أعمل حاليًا على تعديل المستندات الحالية في Kubernetes. وأدّت هذه المساهمات إلى إدراجي كظل في مستند "الإصدارات" ضمن دورة إصدار Kubernetes بإصدار 1.19، حيث أساهم في صيانة مستندات الميزات الجديدة التي تتم إضافتها خلال الإصدارات وترقيتها بشكل فعّال. أعتقد أنّ التوثيق الجيد هو الركيزة الأساسية للمنتج أو الخدمة الرائعة. سواء كانت المعلومات إجرائية أو تقنية، ستكون المعلومات المكتوبة جيدًا والموجزة والتي يسهل الوصول إليها حافزًا في تعزيز الاستخدام والمساعدة في الاستخدام بشكل أفضل. من خلال عملي مع الأنظمة الموزعة المستندة إلى البيانات طوال مسيرتي المهنية، أعتقد أنه من الأفضل فهم التعقيدات في المتطلبات فيما يتعلق بتوثيق هذه الأنظمة. كوني مستخدمًا نهائيًا، وأنا على دراية بصعوبات التوثيق المكتوب/غير الصحيح بشكل سيئ، وسأحرص على مراعاة تلك الأمور أثناء إعادة الهيكل.