تحتوي هذه الصفحة على تفاصيل مشروع كتابة فنية تم قبوله في "موسم مستندات Google".
ملخّص المشروع
- مؤسسة مفتوحة المصدر:
- VideoLAN
- الكاتب الفني:
- إديونغ آني أسيكبو
- اسم المشروع:
- تحديث (إعادة كتابة) مستندات مستخدم VLC
- مدة المشروع:
- المدة العادية (3 أشهر)
وصف المشروع
ABSTRACT
تم تصميم مستندات المستخدمين لمساعدة المستخدمين النهائيين على استخدام منتج أو خدمة. إنّ مستندات المستخدمين الجيدة مهمة جدًا لأنّها توفّر للمستخدمين طريقة لمعرفة كيفية استخدام البرنامج وميزاته ونصائحه وحيل استخدامه، بالإضافة إلى حلّ المشاكل الشائعة التي يواجهونها عند استخدام البرنامج. كما أنه يقلل من تكلفة الدعم ويشكل جزءًا من هوية الشركة للمنتج: حيث أن وثائق المستخدم الجيدة هي علامة على سلامة المنتج، أي فريق المطور.
بدون وثائق مستخدم جيدة، قد لا يعرف المستخدم كيفية القيام بالأشياء المذكورة أعلاه بفعالية وكفاءة. يمكن أن تؤدي مستندات المستخدمين دورًا محوريًا في ضمان نجاح المنتج، لأنّ التواصل الجيد هو أساس أي نشاط تجاري أو منتج، وسيظل كذلك دائمًا، وتأخذ المستندات الجيدة هذا التواصل وتضعه في إطار عمل يمكن للجميع الوصول إليه لتحقيق النجاح.
في وقت كتابة هذه المقالة، تم الوصول إلى مستندات مستخدمي VLC 4,634,065 مرة، ويتم تنزيل مشغّل الوسائط VLC 23 مليون مرة تقريبًا كل شهر من الموقع الإلكتروني الرئيسي، ما يشير إلى أنّ الكثير من المستخدمين حول العالم يستخدمون مشغّل الوسائط VLC وقد يريدون قراءة مستندات المستخدمين للحصول على إرشادات حول كيفية استخدام مشغّل الوسائط. ومع ذلك، فإنّ مستندات المستخدم الخاصة بمشغّل الوسائط VLC قديمة وغير مكتملة حاليًا (تم تعديلها آخر مرة في 28 تشرين الأول (أكتوبر) 2015)، ويريد منتدى VideoLAN استخدام هذا المشروع لتحسين مستندات المستخدمين من أجل منح المستخدمين النهائيين تجربة سلسة عند استخدام مشغّل الوسائط VLC.
الحالة الحالية
تتوفّر حاليًا مستندات المستخدمين على صفحة ويكي. إنّه قديم وغير مكتمل، ويصعب التنقّل فيه أو العثور على المعلومات فيه، ولا يتناول معلومات عن الإصدار الحالي من مشغّل الوسائط، ولا يمكن ترجمته إلا إلى اللغة الألمانية، ما يشكّل عائقًا كبيرًا للأشخاص الذين لا يجيدون قراءة اللغة الإنجليزية.
لماذا تُعدّ مستندات المستخدم المقترَحة تحسينًا على المستندات الحالية؟
سيتم تنظيم مستندات المستخدم المقترَحة لتحسين الكفاءة والاتساق والطمأنينة لدى المستخدم النهائي وضمانها. يجب أن يتضمّن هذا الدليل أدلة مكتوبة وصورًا مرتبطة بها، وأن يتضمن تعليمات وشرحًا حول كيفية استخدام كل ميزة من ميزات مشغّل الوسائط VLC، وأن يكون محدّثًا وسهل التنقّل فيه ومفهومًا وقابلًا للترجمة بخمس لغات رئيسية على الأقل.
المرشدون: جان بابتيست وأليكس وسيمون
التحليل
أجريتُ محادثة مع "جان باتيست" حول البيئة الجديدة التي سيتم نقل مستندات المستخدمين الحالية إليها لإجراء تحسينات، وشارك معي رابطَين يعرضان مستودع Gitlab للملف المصدر المكتوب باستخدام Sphinx والمستندات الرئيسية المستضافة على Read the Docs، وقال إنّه يتوقع أن تكون المستندات الجديدة مشابهة لها. لقد أجريتُ الكثير من الأبحاث حول هذه الأدوات لفهم آلية عملها بشكل أفضل.
أبو الهول
Sphinx هو حلّ قوي ومُعترَف به لمستندات البرامج. يتضمّن هذا الإصدار عددًا من الميزات التي يتوقعها الكتاب، مثل نشر المحتوى من مصدر واحد وإعادة استخدام المحتوى من خلال عمليات التضمين وعمليات التضمين الشَرطية استنادًا إلى نوع المحتوى والعلامات ومظاهر HTML متعددة تقدّم تجربة رائعة للمستخدم على الأجهزة الجوّالة وأجهزة الكمبيوتر المكتبي، والإشارة إلى الصفحات والمستندات والمشاريع إتاحة الفهرس والمسرد ودعم الترجمة والنشر ويستخدم أيضًا لغة الترميز reStructuredText، وتعود العديد من نقاط قوته إلى فعالية لغة reStructuredText وسهولة استخدامها وقدرتها على ترجمة المستندات.
Read the Docs
تعمل خدمة Read the Docs على تبسيط مستندات البرامج من خلال التشغيل الآلي لإنشاء مستنداتك وتحديد إصداراتها واستضافتها نيابةً عنك. لا يتم إيقاف المزامنة أبدًا، أي عند إرسال الرمز إلى نظام التحكّم في الإصدار المفضّل لديك، سواء كان Git أو Mercurial أو Bazaar أو Subversion، ستنشئ Read the Docs مستنداتك تلقائيًا حتى تكون الرموز البرمجية والمستندات محدّثة دائمًا. له إصدارات متعددة؛ يمكن لـ "قراءة المستندات" استضافة إصدارات متعددة من مستنداتك وإنشاءها، لذا فإن الحصول على نسخة 1.0 من مستنداتك ونسخة 2.0 منها أمر سهل مثل وجود فرع أو علامة منفصلة في نظام التحكم في الإصدار لديك. تطبيق Read Along هو تطبيق مجاني ومفتوح المصدر يستضيف مستندات لما يقرب من 100,000 مشروع كبير وصغير مفتوح المصدر بكل لغات البشر والكمبيوتر تقريبًا.
VERDICT
Sphinx هي أداة فعّالة للغاية، وتعمل Read the Docs على توفير استضافة لمستندات Sphinx التي تحافظ على تحديث مستنداتك في جميع الإصدارات. وهما معًا مجموعة رائعة من الأدوات التي يمكن للمطوّرين والكتاب الفنيين استخدامها لإنشاء مستندات المستخدمين التي ستكون الأفضل للمستخدمين النهائيين.
يوفّر Sphinx إمكانية ترجمة الوثائق إلى لغات متعددة. وهو يتيح ميزة التحكّم في الإصدارات التي سيتم استخدامها لإدارة المستندات. على عكس الموسوعة الحالية التي يمكن لأي مستخدم تعديلها وعدم إضافة المعلومات الصحيحة إليها، سيضمن نظام التحكّم في الإصدارات هذا مراجعة جميع التغييرات أولاً قبل دمجها في المستودع الرئيسي. سيؤدي أيضًا التحكّم في الإصدارات إلى زيادة مساهمة البرامج المفتوحة المصدر في المشروع لأنّه يمكن للمستخدمين إنشاء مشاكل وطلبات سحب مفتوحة وما إلى ذلك. ويستخدم Sphinx وRead the Docs قائمة بمجتمعات رائعة أخرى، مثل ASP.NET وKernel وJulia وJupyter وPHPMyAdmin وWrite the Docs وما إلى ذلك، وهي أداة رائعة لاستخدامها في مستندات مستخدمي VLC الجديدة.
لم أقرأ فقط عن هذه الأدوات، بل أنشأت أيضًا عيّنة أساسية. في ما يلي الرابط: https://gitlab.com/Didicodes/demo-vlc-user-documentation إلى مستودع Gitlab الخاص بي، في حين يمكن العثور على الإصدار المستضاف على readthedocs هنا: [https://vlc-user-documentation-demo.readthedocs.io/en/latest/](https://vlc-user-documentation-demo.readthedocs.io/en/latest/.
بنية المستندات المقترَحة
لقد أنشأت بنية لمستندات مستخدمي VLC والتي يمكن العثور عليها هنا: https://docs.google.com/document/d/1Sy2V2IADoCyfnGBK70v8mkjiWK2tH-oWdUlDxAfQAYA/edit?usp=sharing. قبل بدء تنفيذ هذه البنية الجديدة، يجب أن يوافق عليها المرشدون. وهذا يعني أنّه من المرجّح أن تتغيّر البنية بعد أن يراجعها المرشدون.
أهداف المشروع
- إعادة تنظيم المستندات
- يُرجى تعديل المستندات لتلائم الإصدارات الحديثة من VLC.
- يمكنك نقل مستندات المستخدم إلى Gitlab باستخدام Sphinx وReadthe Docs.
- إزالة الصور والمعلومات القديمة
- إعادة كتابة مستندات المستخدمين لتسهيل فهمها
- إعداده للترجمة باستخدام ميزة Sphinx Internationalization
- اجعل المستندات مستندة إلى المنتدى حتى يتمكّن المستخدمون من الإبلاغ عن أي مشاكل تواجههم أثناء قراءة المستندات أو حلّها.
ما سبب هذا المشروع؟
لطالما اعتقدت أنّ كتابة الرموز البرمجية وحلّ المشاكل وإنشاء البرامج تحقّق إمكاناتها الكاملة عندما يكون لديك أيضًا القدرة على إطلاع الآخرين عليها من خلال الكتابة. لقد أعجبتني دائمًا الجهود التي يبذلها منتدى VideoLAN في إنشاء حلول برمجية مجانية للوسائط المتعددة. عندما كنت طفلاً، كان مشغّل الوسائط VLC هو البرنامج الذي كنت أستخدمه دائمًا عند الاستماع إلى الموسيقى أو مشاهدة فيلم لأنّه كان صوته مرتفعًا جدًا وكان يتضمّن العديد من الميزات. سيكون من دواعي سروري العمل مع المنتدى الذي ساهم في جعل طفولتي رائعة.
سبب اختياري لهذا المشروع
أعتقد أنّني الشخص المناسب لهذا المشروع لأنّ:
- لديّ خبرة سابقة في تحسين مستندات المؤسسات ويمكنني استخدام أي نظام تحكّم في الإصدارات، لذا لن تكون هناك مشكلة في تنفيذ الأوامر على Gitab. علاوة على ذلك، ما يدفعني هو العمل في مشروعات تخلق قيمة للأشخاص.
- أعتقد أنّه إذا أردت من أحد الأشخاص تنفيذ مهمة ما بأكبر قدر ممكن من الكفاءة، عليك توثيقها. من خلال توثيق عملياتك، يمكنك ضمان الكفاءة والاتساق وراحة البال لأي شخص معنيّ.
- أعرف احتياجات مستخدمي VLC لأنّني أحدهم. سيتيح لك ذلك كتابة المستندات بطريقة يفهمها كل مستخدم في جميع أنحاء العالم من النظرة الأولى.