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