تحتوي هذه الصفحة على تفاصيل مشروع كتابة فنية تم قبوله في "موسم مستندات Google".
ملخص المشروع
- مؤسسة مفتوحة المصدر:
- مؤسسة Linux
- الكاتب التقني:
- البورون
- اسم المشروع:
- إعادة صياغة المستندات وإنشاءها وإعادة تنظيم صفحات البدء وأدلة المطوّرين
- مدة المشروع:
- المدة العادية (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-grad-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 على روابط تؤدي إلى جميع ملفات yaml الخاصة بالكتاب، ويستمر في جلب جميع ملفات yaml الخاصة بالكتاب من المستودعات البعيدة إلى docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate]. تحتوي ملفات yaml الخاصة بالكتب على جميع عناوين URL الخاصة بملفات Markdown من المستودع البعيد.
- بعد جلب جميع ملفات Markdown، تعالج الأدوات إنشاء الموقع الإلكتروني لمستندات AGL في docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] الذي يتم نشره وفقًا لذلك.
- إنّ العملية الحالية للحفاظ على مسار الإصدار ليست سهلة الاستخدام والمطوّرين، لا سيما للمساهمين الجدد. يمكن تبسيط مسار سير العمل هذا (لإنشاء التطبيق واستضافته) وتسهيله أكثر كي يتمكّن المطوّرون من التركيز على جزء التوثيق بدلاً من الحفاظ على سير عمل إنشاء التوثيق ونشره.