تحتوي هذه الصفحة على تفاصيل مشروع كتابة تقنيّة تم قبوله في موسم المستندات من Google.
ملخص المشروع
- المؤسسة المفتوحة المصدر:
- VLC
- الكاتب التقني:
- أبهيشيك براتاب سينغ
- اسم المشروع:
- مواصلة تحديث مستندات مستخدمي VLC
- مدة المشروع:
- المدة العادية (3 أشهر)
وصف المشروع
الحالة الراهنة للوثائق
جارٍ تحديث مستندات مستخدمي VLC وتعديلها. عملية النقل قيد التقدم للانتقال من الوثائق القديمة المستندة إلى موقع wiki[1] إلى وثائق المستخدم الحديثة التي تم إنشاؤها بواسطة sphinx[2] المستضافة على ReadThe Docs.
الجمهور المستهدف
إنّ الجمهور المستهدف هو أحد المستخدمين الفضوليين الذين يرغبون في استكشاف ميزات مشغّل وسائط VLC بشكل يتجاوز مشغّل الوسائط العادي، وسيساعد إلى حدّ ما مطوّري البرامج أيضًا من خلال العمل كدليل مرجعي سهل الاستخدام. وبالتالي، أخطط لتضمين التعليمات المستندة إلى واجهة المستخدم التصويرية (GUI) (إلى جانب الصور عند الاقتضاء) والطرق المستندة إلى واجهة سطر الأوامر (إلى جانب مقتطفات الرموز) حتى يكون لدى المستخدم النهائي حرية الاختيار.
وأعتقد أنّه يجب تخفيض لغة الوثائق (خاصةً في قسم واجهة المستخدم الرسومية) بدرجة كافية كي يتمكّن من فهم الدليل وتنفيذه من قِبل شخص لديه قدر ضئيل من الخبرة على تشغيل أجهزة الكمبيوتر. من ناحية أخرى، ينبغي ألا تكون طويلة جدًا أو تفسيرية (خاصةً قسم واجهة سطر الأوامر) لدرجة أن المبرمجين لا يهتمون بهذا الموضوع.
يمكن تحقيق التوازن الصحيح عن طريق ذكر المتطلبات الأساسية في بداية الصفحة أو الاحتفاظ بالأقسام الاختيارية التي يمكن للخبراء تجاوزها.
بهدف إنشاء الترجمة، يكون الجمهور المستهدَف هو مطوري/مستخدمي VLC الذين يجيدون اللغة الإنجليزية واللغة التي يريدون الترجمة إليها.
الأدوات
وستعمل أداة Sphinx على إعداد الوثائق الجديدة، كما تتم استضافتها على ReadTheDocuments، كما يتم تطبيق نظام التحكم في الإصدار في برنامج GitLab. لقد اكتسبت بعض الخبرة السابقة في استخدام Git وGitHub، مما ساعدني في التعرف على GitLab، على الرغم من وجود بعض الميزات المختلفة التي استغرق التعلم بعض الوقت.
أما بالنسبة إلى Sphinx، فقد قرأت عن هذا الأمر عندما أشار أحد الزملاء من محبّي البرامج المفتوحة المصدر إلى عدد المؤسسات التي تستخدمها لبناء وثائقها (مع مثال بارز لـ Blender، والذي يستخدم Sphinx لإنشاء دليل المستخدم[3] ووثائق واجهة برمجة التطبيقات[4]).
كنت على دراية بعض الشيء بـ ReadThe Docs، وهي أداة جيدة لتحديد الإصدارات واستضافة المستندات الفنية. وبالتالي، تمكنت من إنشاء وثائق VLC بدون الكثير من المشكلات وأنا على دراية بالنص المُعاد تنظيمه، وهو التنسيق المستخدم.
بالنسبة إلى الترجمات، يستخدم برنامج VLC Babel لإنشاء ملفات po .من أجل تنفيذ i18n وl10n. حاليًا، أتعرّف على سير عمل Babel وكيفية إنشاء ملفات mo .باستخدام Sphinx.
أعتزم استخدام فترة الربط لأتعرّف بشكل أكبر على التفاصيل المعقدة للأدوات المذكورة أعلاه.
التسليمات والجدول الزمني الأسبوعي
في إطار مشروع 2019، تمت تغطية أجزاء من التركيبة والواجهة والصوت والفيديو والتشغيل وغير ذلك (معظم الوظائف الأساسية). وبالتالي، بالنسبة إلى مشروع 2020، أريد تعديل قسم الاستخدام المتقدّم ضمن مستندات المستخدم والعمل عليه.
التسليم 1 [الأسبوع 1-2]: تعديل مستندات Transcode، كما هو مذكور في رقم 7[5].
- تحويل الترميز
- تحويل ترميز فيديوهات متعددة
- أضف شعارًا
- دمج الفيديوهات معًا
- استخراج الصوت واستخراج الصوت من ملف
- نسخ قرص DVD
التسليم الثاني [الأسبوع 3-4]: التحديث باستخدام برنامج VLC كمكوّن إضافي على الويب[6] أثناء الاختبار في Firefox 77 وChrome 83 وEdge 83.
- إنشاء صفحات ويب باستخدام الفيديو
- تضمين سمات العلامات
- وصف واجهة برمجة التطبيقات JavaScript
التسليم 3 [الأسبوع 5]: اختبِر أوامر واجهة سطر الأوامر[7] وعدِّلها وفقًا لذلك.
- عدد مرّات المشاهدة
- اختيار الوحدات
- خيارات خاصة بالعناصر
- الفلاتر
الأسبوع 6: أسبوع التخزين الاحتياطي للمُخرَجات النهائية الثلاثة المذكورة أعلاه.
التسليم 4 [الأسبوع 7-8]: الاستعداد للترجمة. بالإضافة إلى تعديل المعلومات، سأتقدّم بطلب للترجمات إلى لغات أخرى. وهذا أمر مهم لأنّه بعد الترجمة، سيتمكن المستخدمون الذين ليس لديهم خلفية باللغة الإنجليزية من قراءة المستندات (ومن ناحية أخرى، سيكون برنامج VLC أقرب إلى تحقيق الهيمنة العالمية[8]).
كما هو مذكور في قسم "الأدوات" بالاقتراح، يستخدم برنامج VLC حاليًا برنامج Babel لإنشاء ملفات .po للترجمات. سأقوم بتوثيق العملية للمستخدم/المتطوع من أجل:
- نزِّل الوثائق الأساسية وأنشئها محليًا.
- استخدِم Babel لإنشاء الملفات المطلوبة.
- أدخِل ترجمات للسلاسل.
- إنشاء الوثائق المترجمة باستخدام Sphinx.
- نفّذ التغييرات.
التسليم 5 [الأسبوع 9-10]: استعد لوثائق الوحدات. وفقًا لما ناقشناه مع المرشدين، أخطط للتحضير لوثائق الوحدات في جزأين.
الجزء الأول: إنشاء ملفات بالقرب من الوحدات من خلال نص برمجي يبحث عن خيارات صالحة من قاعدة الرمز ويستخرج استخدامها من سطر واحد (والقيم الافتراضية) من صفحات wiki المقابلة سيكون هذا بمثابة مسودة أساسية.
الجزء - 2: بناء هيكل خاص بنظام التشغيل يربط جميع الوحدات + المكونات الإضافية + الخيارات لنظام أساسي معين (Windows، وإذا سمح الوقت، بالنسبة إلى Fedora أيضًا).
سيضمن إنشاء ملفات بالقرب من الوحدات أن تكون الوثائق قريبة من رمز المصدر. باستخدام نهج من أسفل، سيتم بناء وثائق الوحدات الرئيسية من خلال دمج الملفات المعدة في الجزء - الأول واستخدام الهيكل المصمم في الجزء - الثاني كمرجع.
ستحتاج الملفات التي تم إنشاؤها من خلال التشغيل الآلي إلى مراجعة، لكن الأولوية الأولى هي وضع إطار عمل فعال. بعد إتمام ذلك، سأراجع الملفات للتأكّد من الخيارات المتاحة. يتم تحديد أولوية إطار العمل فور توفّره، ويمكن للمطوّرين والقائمين على الصيانة أيضًا البدء في المساهمة من خلال إضافة حالات استخدام ذات صلة.
تسليم المكافأة [الأسبوع 11]: الاستعداد للإصدار 4.0. في حالة بقاء المشروع ضمن الجدول الزمني، فأنا أود اقتراح مُخرَج نهائي إضافي. وفقًا لما ناقشناه مع المرشدين، يتضمن التحضير للإصدار 4.0 وجود وثائق مستقرة وكاملة تقريبًا للإصدار 3.0.
وبالتالي، سنراجع الوثائق المكتملة للأقسام التالية للتحقق من الطرق المذكورة وتحديثها:
- الاستخدام الأساسي: الوسائط، والتشغيل، والصوت، والفيديو، والترجمة، ومفاتيح التشغيل السريع، والتسجيلات، والإعدادات، والنصائح والحيل
- الاستخدام المتقدم: مشغّل، وواجهة، وTranscode، وبث، وحالات غير معتادة
- الإضافات: الإضافات والمظاهر
الأسبوع 12: أسبوع التخزين الاحتياطي للمُخرَجات النهائية الثلاثة المذكورة أعلاه + التقارير النهائية.
لماذا أنا الشخص المناسب لهذا المشروع؟
بصفتي من عشاق التكنولوجيا، فلديّ خبرة في استخدام/اختبار البرامج، وفي بعض الأحيان أحاول فهم قواعد التعليمات البرمجية لديها. في الواقع، كانت محاولة فهم قاعدة الرموز لمؤسسة مفتوحة المصدر هي المرة الأولى التي أدركت فيها حقًا أهمية التوثيق. بالإضافة إلى ذلك، وبصفتي من هواة الموسيقى، فلديّ خبرة كبيرة في تعديل المحتوى باستخدام VLC :).
وبالإضافة إلى ذلك، كنت باحثة وكاتبة طوال حياتي. ما لم أكتب شيئًا ما، لا أفهمه أبدًا، وهذه العادة جعلتني مدوّن ملاحظات ووثيقة فعّالة.
نقطة الالتقاء بين هاتين العادتين هي ما يجعلني مناسبًا تمامًا للتوثيق الفني. يمكنني أن أجد طريقي من خلال الجوانب الفنية إلى جانب توثيق النتائج/العمليات بطريقة يفهمها المستخدمون.
الروابط: [1] https://wiki.videolan.org/Documentation:User_Guide/ [2] https://vlc-user-documentation.readthedocs.io/ar/latest/index.html [3] https://docs.blender.org/manual/ar/latest/ [4] https://docs.blender.org/api/current/index.wikidocs/docs.lanc بمقدار 5