تحتوي هذه الصفحة على تفاصيل مشروع كتابة فنية تم قبوله في "موسم مستندات Google".
ملخّص المشروع
- مؤسسة مفتوحة المصدر:
- VLC
- الكاتب الفني:
- أبهيشيك براتاب سينغ
- اسم المشروع:
- مواصلة تحديث مستندات مستخدمي VLC
- مدة المشروع:
- المدة العادية (3 أشهر)
وصف المشروع
الحالة الحالية للمستندات
نحن بصدد تحديث مستندات المستخدمين في VLC وجعلها حديثة. يتم حاليًا الانتقال من الوثائق القديمة المستندة إلى موقع wiki[1] إلى وثائق المستخدم الحديثة المصممة على Sphinx[2] والتي تتم استضافتها على ReadThe Docs.
الجمهور المستهدَف
يشمل الجمهور المستهدَف المستخدمين الفضوليين الذين يريدون استكشاف ميزات مشغّل وسائط VLC التي تتجاوز ميزات مشغّل الوسائط العادي، كما سيساعد المطوّرين إلى حدّ ما من خلال تقديم دليل مرجعي سهل. وبالتالي، أخطّط لتضمين كلّ من التعليمات المستندة إلى واجهة المستخدم الرسومية (بالإضافة إلى الصور عند الاقتضاء) والأساليب المستندة إلى واجهة سطر الأوامر (بالإضافة إلى مقتطفات الرموز البرمجية) حتى يحصل المستخدم النهائي على حرية الاختيار.
أعتقد أنّه يجب تقليل لغة الوثائق (وخاصةً قسم واجهة المستخدم الرسومية) بدرجة كافية بحيث يمكن للشخص الذي يتعرّض اسميًا لأجهزة الكمبيوتر التي تعمل بنظام التشغيل فهم الدليل وتنفيذه. من ناحية أخرى، يجب ألّا يكون الدليل طويلاً أو توضيحيًا جدًا (خاصةً قسم واجهة سطر الأوامر) لدرجة أن يفقد المبرمجون الاهتمام به.
ويمكن تحقيق التوازن الصحيح من خلال ذكر المتطلبات الأساسية في بداية الصفحة أو الاحتفاظ بأقسام اختيارية يمكن للمتمرّسين تخطّيها.
ولتقديم خدمات الترجمة، يجب استهداف مطوّري أو مستخدمي VLC الذين يجيدون اللغة الإنجليزية واللغة التي يريدون الترجمة إليها.
الأدوات
يتم إنشاء المستندات الجديدة باستخدام Sphinx ويتم استضافتها على ReadTheDocs، ويتم تنفيذ نظام التحكّم في الإصدارات في 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]: تعديل مستندات تحويل الترميز، كما هو موضّح في النقطة 7[5].
- تحويل الترميز
- تحويل ترميز فيديوهات متعددة
- أضف شعارًا
- دمج الفيديوهات معًا
- استخراج الصوت واستخراج الصوت من ملف
- نسخ محتوى أسطوانة DVD
قابل للتنزيل 2 [الأسبوع من 3 إلى 4]: تحديث استخدام VLC كمكوّن إضافي للويب[6]، أثناء الاختبار في Firefox 77 وChrome 83 وEdge 83
- إنشاء صفحات ويب تتضمّن فيديو
- سمات العلامات المضمّنة
- وصف JavaScript API
التسليم 3 [الأسبوع 5]: اختبار أوامر واجهة سطر الأوامر[7] وإجراء التعديلات وفقًا لذلك
- عدد مرّات المشاهدة
- اختيار الوحدات
- الخيارات الخاصة بالسلعة
- الفلاتر
الأسبوع 6: أسبوع التخزين المؤقت للمُخرَجات النهائية الثلاثة المذكورة أعلاه.
قابل للتسليم 4 [الأسبوع من 7 إلى 8]: استعِدّ للترجمة. بالإضافة إلى التحديث، سأحضّر للترجمات إلى لغات أخرى. هذا مهم لأنّه بعد الترجمة، سيتمكّن المستخدمون الذين لا يجيدون اللغة الإنجليزية من قراءة المستندات (وعلى الجانب ذي الصلة، سيكون VLC أقرب خطوة إلى تحقيق الهيمنة على العالم[8]).
كما هو موضّح في القسم "أدوات" ضِمن الاقتراح، يستخدم VLC حاليًا Babel لإنشاء ملفات .po بهدف الترجمة. سأوثق العملية للمستخدم/المتطوع من أجل:
- نزِّل المستندات الأساسية وانشئها على الجهاز.
- استخدِم Babel لإنشاء الملفات المطلوبة.
- أدخِل الترجمات للسلاسل.
- إنشاء المستندات المترجَمة باستخدام Sphinx
- احفظ التغييرات.
المنتج 5 [الأسبوعان 9 و10]: الاستعداد لتوثيق الوحدات وفقًا لما ناقشناه مع المرشدين، أخطّط لإعداد مستندات الوحدات في جزأين.
الجزء الأول: إنشاء ملفات بالقرب من الوحدات من خلال نص برمجي يبحث عن خيارات صالحة من قاعدة الرموز ويستخرج استخدام سطر واحد (والقيم الافتراضية) من صفحات موقع wiki المقابلة. سيكون هذا بمثابة مسودة أساسية.
الجزء الثاني: إنشاء بنية خاصة بمنصّة معيّنة تربط جميع الوحدات والمكونات الإضافية والخيارات بمنصّة معيّنة (Windows، وFedora أيضًا إذا سمح الوقت بذلك)
سيضمن إنشاء الملفات بالقرب من الوحدات أن تكون المستندات قريبة من رمز المصدر. باستخدام نهج من الأعلى، سيتم إنشاء وثائق الوحدات الرئيسية من دمج الملفات التي تم إنشاؤها في الجزء - الأول واستخدام البنية التي تم إنشاؤها في الجزء - الثاني كمرجع.
ستحتاج الملفات التي تم إنشاؤها من خلال التشغيل الآلي إلى مراجعة، ولكن الأولوية الأولى هي إنشاء إطار عمل وظيفي. بعد تحقيق ذلك، ووفقًا للوقت المتاح، سأراجع الملفات للتحقّق من الخيارات. يتم منح الأولوية للإطار بعد أن يصبح متاحًا، إذ يمكن للمطوّرين والمشرفين أيضًا البدء في المساهمة من خلال إضافة حالات الاستخدام ذات الصلة.
التسليم الإضافي [الأسبوع 11]: الاستعداد لإصدار 4.0 في حال استمرار المشروع على المسار الصحيح، أودّ اقتراح منتج إضافي. كما ناقشنا مع الخبراء، يتطلّب الاستعداد لإصدار 4.0 توفُّر مستندات ثابتة وكاملة تقريبًا للإصدار 3.0.
وبالتالي، سأراجع المستندات المكتملة من الأقسام التالية للتحقّق من الطرق المذكورة وتعديلها:
- الاستخدام الأساسي: الوسائط، التشغيل، الصوت، الفيديو، الترجمة والشرح، مفاتيح التشغيل السريع، التسجيلات، الإعدادات، النصائح والحيل
- الاستخدام المتقدّم: المشغّل، الواجهة، تحويل الترميز، البث، الحالات غير المعتادة
- الإضافات: الإضافات والمظاهر
الأسبوع 12: أسبوع احتياطي لتسليم العناصر الثلاثة أعلاه + التقارير النهائية
لماذا أنا الشخص المناسب لهذا المشروع؟
بصفتي من المهتمين بالتكنولوجيا، لديّ خبرة في استخدام/اختبار البرامج، وفي بعض الأحيان، أحاول فهم قواعد الرموز البرمجية. في الواقع، كانت محاولة فهم قاعدة الرموز البرمجية لمؤسسة مفتوحة المصدر هي المرة الأولى التي أدرك فيها حقًا أهمية التوثيق. بالإضافة إلى ذلك، بصفتي أحد محبّي الموسيقى، أملك خبرة واسعة في التعامل مع مشغّل الفيديو VLC :)
بالإضافة إلى ذلك، عملتُ باحثًا وكاتبًا طوال حياتي. ما لم أكتب شيئًا ما، لا أفهمه أبدًا، وقد جعلتني هذه العادة مدوّنًا وموثّقًا فعالاً.
إنّ تقاطع هاتين العادتَين هو ما يجعلني مناسبًا لكتابة الوثائق الفنية. يمكنني التعرّف على الجوانب التقنية وتوثيق النتائج والعمليات التي توصّلت إليها بطريقة يفهمها المستخدمون.
الروابط: [1] https://wiki.videolan.org/Documentation:User_Guide/ [2] https://vlc-user-documentation.readthedocs.io/en/latest/index.html [3] https://docs.blender.org/manual/en/latest/ [4] https://docs.blender.org/api/current/index.html [5] https://code.videolan.org/docs/vlc-user/-/issues/7 [6] https://wiki.videolan.org/Documentation:WebPlugin/ [7] https://wiki.videolan.org/Documentation:Command_line/ [8] https://trac.videolan.org/vlc/ticket/35