تحتوي هذه الصفحة على تفاصيل مشروع الكتابة الفنية الذي تم قبوله في Google Season of Docs.
ملخّص المشروع
- المؤسسة المفتوحة المصدر:
- The Linux Foundation
- الكاتب الفني:
- boron
- اسم المشروع:
- Rework the documentation hosting &generation and Restructure getting started pages and developer guides.
- مدة المشروع:
- المدة العادية (3 أشهر)
وصف المشروع
الملخّص :
تم تصميم المستندات لمساعدة المستخدِمين النهائيين والمطوّرين على استخدام منتج أو خدمة. تتسم المستندات الجيدة بأهمية كبيرة لأنّها تتيح للمستخدِمين تعلُّم كيفية استخدام برنامج وميزاته ونصائحه وحيله، وحل المشاكل الشائعة التي تواجههم عند استخدامه. تساهم المستندات أيضًا في خفض تكلفة الدعم وتشكّل جزءًا من هوية المنتج على مستوى الشركة والمصادر المفتوحة، فالمستندات الجيدة تشير إلى سلامة المنتج وفريق المطوّرين.
بدون مستندات جيدة، قد لا يعرف المستخدِم كيفية تنفيذ الإجراءات المذكورة أعلاه بفعالية وكفاءة. يمكن أن تؤدي المستندات دورًا محوريًا في ضمان نجاح المنتج لأنّ التواصل الرائع هو وسيبقى أساس أي عمل تجاري أو منتج، والمستندات الرائعة تأخذ هذا التواصل وتضعه في إطار عمل قابل للإدارة يمكن للجميع الوصول إليه لتحقيق النجاح.
يحتاج كل موقع إلكتروني للمستندات إلى مسار سير عمل جيد للإنشاء والاستضافة. في مؤسسة مثل AGL، التي تتضمّن إصدارات متعددة والكثير من المستندات التفصيلية، يتم توزيع ملفات المستندات (ملفات Markdown) على مستودعات متعددة، ما يجعل مهمة صيانتها وتعديلها معقدة للغاية وتستغرق وقتًا طويلاً.
الحالة الحالية :
- يستند الموقع الإلكتروني لمستندات AGL إلى مجموعة من ملفات Markdown التي يتم جلبها من مستودعات مختلفة.
- تتم حاليًا استضافة صفحات المستندات ضمن المصادر الفردية بتنسيق Markdown باستخدام محرّك مشروع Cordova.
- يؤدي ذلك إلى إعداد أربعة مستودعات لعملية إنشاء المستندات واستضافتها :
- Docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] : يحتوي على نموذج الموقع الإلكتروني Jekyll.
- Docs-tools [https://github.com/automotive-grade-linux/docs-tools] : يحتوي على أدوات لإنشاء موقع إلكتروني فني تلقائيًا من ملفات Markdown.
- Docs-sources [https://github.com/automotive-grade-linux/docs-sources] : المصدر (ملفات Markdown [https://github.com/automotive-grade-linux/docs-sources/tree/master/docs]) للمستندات والأدلة العامة.
- Docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] : مستودع صفحات GitHub المنشورة للموقع الإلكتروني للمستندات [https://gist.github.com/growupboron/docs.automotivelinux.org].
- تتولى أداة (نص برمجي) متاحة في docs-tools [https://github.com/automotive-grade-linux/docs-tools] جمع جميع ملفات Markdown ووضعها في قوالب وفقًا لملف fetched_files.yml الموجود في docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate].
- سير العمل الحالي لإنشاء الموقع الإلكتروني لمستندات AGL : current_workflow [https://drive.google.com/file/d/1OSwkVWFcsajgCOjbtdPf42EIfpidUJ0U/view?usp=sharing]
- يحتوي ملف section_version.yml على روابط لجميع ملفات book yaml، ويتم جلب جميع ملفات book yaml من المستودعات البعيدة إلى docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate]. تحتوي ملفات book yaml على جميع عناوين URL لملفات Markdown من المستودع البعيد.
- بعد جلب جميع ملفات Markdown، تعالج الأدوات عملية إنشاء الموقع الإلكتروني لمستندات AGL في docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] الذي يتم نشره وفقًا لذلك.
- لا تتسم العملية الحالية لصيانة مسار سير العمل بالسهولة للمستخدِمين والمطوّرين، وخاصةً المساهمين الجدد. يمكن تبسيط مسار سير العمل هذا (للإنشاء والاستضافة) وتسهيله بشكل أكبر ليتمكّن المطوّرون من التركيز على جزء المستندات بدلاً من صيانة سير عمل إنشاء المستندات ونشرها.