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