تحتوي هذه الصفحة على تفاصيل مشروع كتابة فنية تم قبوله في "موسم مستندات 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 Pages. لكي يحافظ هذا المشروع على سير عمل النشر الحالي، سأجد طريقة لنشر مظهر Hugo Docsy في Gitlab Pages.
النتائج المتوقّعة للمشروع: - موقع إلكتروني للمشروع مُبسّط يدمج الوثائق ومراجع الرموز البرمجية والأدلة التعليمية والأخبار. - دليل مستخدم مُعاد تنظيمه ومراجعته يفصل المحتوى المخصّص للمستخدمين والمطوّرين، ويتضمن معلومات كانت غير متوفّرة من قبل - سير عمل البرامج التعليمية من الأمثلة المتاحة لمستندات التعليمات والأسئلة الشائعة والمشاكل الشائعة
أدوات المشروع تستخدم مستندات Allpix Squared الحالية LaTeX وDoxygen وpandoc وHugo بالإضافة إلى GitLab وGitlab CI. لقد تحدّثنا مع مشرفي المشروع عن إمكانية نقل المحتوى من LaTeX إلى Markdown باستخدام مكوّنات MathJax الإضافية. إذا نجحت، سيتضمّن سير عمل المستندات Hugo وMarkdown وDoxygen وgit وGitlab CI. لإبقاء الأدلة التعليمية ضمن الموقع الإلكتروني أو المنصة نفسها، سأستخدم Hugo وMarkdown. أريد معرفة مدى إمكانية استخدام "الدروس التطبيقية حول الترميز" (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 أسابيع (مرحلة تطوير المستندات)