تحتوي هذه الصفحة على تفاصيل مشروع كتابة تقنيّة تم قبوله في موسم المستندات من Google.
ملخص المشروع
- المؤسسة المفتوحة المصدر:
- CERN-HSF
- الكاتب التقني:
- SabitaR
- اسم المشروع:
- إعادة تنظيم مستندات Allpix Squared وتبسيطها
- مدة المشروع:
- المدة العادية (3 أشهر)
وصف المشروع
نظرة عامة لقد اخترت مشروع Allpix Squared التابع للمنظمة الأوروبية للأبحاث النووية (CERN-HSF) لسببين رئيسيين:
بناء المهارات: الوثائق الحالية لهذا المشروع شاملة وتدمج تنسيقات محتوى متعددة. ستساعدني مراجعة مجموعة المستندات الشاملة هذه وإعادة تنظيمها في صقل بنية المعلومات ومهاراتي في الكتابة. بالإضافة إلى ذلك، لم يعد مجال المشروع (فيزياء الجسيمات) جديدًا بالنسبة إليّ. فهو يتحداني في صقل مهاراتي في التفاعل مع المطورين. وأعتقد أنّ الكُتّاب التقنيين يمكنهم معالجة إدخالات من المطوّرين وتقديم محتوى مفيد لأي مستوى من المستخدمين، إذا أجرينا أبحاثنا الأساسية المطلوبة وطرحنا الأسئلة المناسبة. سيتيح لي هذا المشروع اختبار هذه النظرية!
المعرفة الفنية: يتطلب هذا المشروع Hugo، وهي أداة تظهر في مقدمة قائمة التعلُّم. أتطلّع إلى التعرُّف على سير عمل LaTeX-Markdown-Hugo-GitLab-CI.
أثناء مرحلة استكشاف الكاتب التقني، تفاعلت مع موجهي المشروع لفترة وجيزة وتعرفت على هيكل مجموعة المستندات الحالي. أنشأت أيضًا موقعًا إلكترونيًا تجريبيًا (https://ap2-demo.netlify.app/) لاختبار ما إذا كان بإمكاني إعداد Hugo و Docsy بشكلٍ صحيح على الجهاز الذي يعمل بنظام التشغيل Windows. تمكنت من نشر الموقع على Netlify ولكن ليس على صفحات Gitlab. لكي يحافظ هذا المشروع على سير عمل النشر الحالي، سأعثر على طريقة لنشر مظهر Hugo Docsy على صفحات Gitlab.
نتائج المشروع المتوقعة - موقع ويب مبسط للمشروع يدمج الوثائق ومراجع التعليمات البرمجية والبرامج التعليمية والأخبار. - دليل المستخدم المعاد تنظيمه ومراجعته الذي يفصل المحتوى المخصص للمستخدمين والمطورين، ويتضمن معلومات مفقودة سابقًا. - سير عمل البرامج التعليمية من الأمثلة المتاحة لوثائق كيفية الاستخدام والأسئلة الشائعة والمشكلات الشائعة.
أدوات المشروع تستخدم الوثائق الحالية لشركة Allpix Squared LaTeX وDoxygen وpandoc وHugo، بالإضافة إلى GitLab وGitlab CI. لقد تحدثت مع مرشدي المشروع وحول إمكانية نقل المحتوى من LaTeX إلى Markdown باستخدام مكونات MathJax الإضافية. إذا نجحت، سيشمل سير عمل المستند Hugo و Markdown وDoxygen وgit وGitlab CI. لإبقاء البرامج التعليمية ضمن نفس موقع الويب/المنصة، سأستخدم Hugo و Markdown. يهمني معرفة إمكانية استخدام أداة Codelabs-as-a-Tool (اختصارها ClaaT) للدروس التعليمية. في شهر تموز (يوليو) القادم، آمل أن أختبر سير العمل مع ClaaT-Hugo وناقشه مع الموجّهين، عند اختيارهم.
مدة المشروع أطلب إكمال مشروع Allpix Squared في غضون فترة ثلاثة أشهر عادية (من 14 سبتمبر 2020 إلى 30 نوفمبر 2020)، والتي سأقضي خلالها 15 ساعة تقريبًا في الأسبوع. ستتضمن هذه الساعات اجتماعات الموجه ورسائل البريد الإلكتروني ذات الصلة، حسب الحاجة. كما سألتزم بجداول GSoD الزمنية للترابط بين أفراد المنتدى ووضع اللمسات الأخيرة على المشروع.
مهام المشروع إليك الطريقة التي أنوي بها تنفيذ التحديثات المقترحة على مجموعة مستندات Allpix Squared الحالية: 1. البحث والمناقشة واستكشاف الخيارات (17 آب (أغسطس) - 13 أيلول (سبتمبر) 2020): - فهم متطلبات المشروع - تثبيت برنامج Allpix Squared لتحديد المعلومات الناقصة، إن وجدت، في المستندات الحالية. - اطلب بيانات الاعتماد اللازمة. - إنشاء مهام سير عمل للمستخدمين المختلفين في Allpix Squared - تصنيف المحتوى حسب دور المستخدم - التحقّق من الآثار المترتبة على تحويل ملفات LaTeX إلى Markdown - دمج مستودعات المصدر أو فهم كيفية العمل باستخدام مستودعات git متعددة - ميزة إضافية: اختبار CLaaT كخيار للدروس التعليمية - دليل مرحلة المساعدة للمساهمين: دليل منهجي لمساعدة المساهمين في إنشاء مخطط زمني سريع
إعادة هيكلة المحتوى ومراجعته وتحسينه (14 أيلول (سبتمبر) - 19 تشرين الأول (أكتوبر) 2020): مهمتان في الأسبوع، من 5 إلى 7 ساعات تقريبًا لكل مهمة. يتضمن هذا المخطط الزمني أسبوعًا احتياطيًا لمعالجة التأخيرات أو المشاكل غير المتوقعة.
- مراجعة تصنيفات المستخدمين والمحتوى الحالي مع وضع سير عمل المستخدمين في الاعتبار
- وضع مخطط لسير عمل المحتوى المُعاد تنظيمه واختباره لمختلف المستخدمين
- مصدر المحتوى الناقص وتحسينه
- تحويل ملفات LaTeX إلى Markdown
- إنهاء دليل المستخدم وجدول محتويات دليل المطوِّر
- إنشاء ملفات PDF لأدلة المستخدم والمطوّرين
- ميزة إضافية: تنظيم محتوى البرامج التعليمية استنادًا إلى الأمثلة والأعداد
- ميزة إضافية: إعداد سير عمل تعليمي للأمثلة على كيفية التنفيذ المخطط الزمني: 5 أسابيع (مرحلة تطوير المستند)
أنشئ الموقع الإلكتروني (19 أكتوبر - 30 نوفمبر 2020): مهمة واحدة إلى اثنتين في الأسبوع، حوالي 5-7 ساعات لكل مهمة. يتضمن هذا المخطط الزمني أسبوعًا احتياطيًا لتحديد المشاكل وحلّها وضبط المخرجات النهائية.
- فهم سير عمل النشر واختباره
- بناء هيكل موقع ويب باستخدام Hugo و Docsy
- اختبار كيفية الحفاظ على سير العمل والنشر التلقائي الحالي باستخدام Docsy
- سحب المحتوى من Doxygen
- تطوير دليل المستخدم ودليل المطوِّر والبرامج التعليمية من محتوى LaTex أو Markdown
- إنهاء شكل وأسلوب موقع الويب للمشروع (الشعار والألوان والقالب والتخطيط والروابط وقابلية الاستخدام وأداة Gitlab CI/CD) المخطط الزمني: 6 أسابيع (مرحلة تطوير المستند)