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