تحتوي هذه الصفحة على تفاصيل مشروع كتابة تقنيّة تم قبوله في موسم المستندات من Google.
ملخص المشروع
- المؤسسة المفتوحة المصدر:
- VideoLAN
- الكاتب التقني:
- إديونغ آني أسيكبو
- اسم المشروع:
- تحديث مستندات مستخدم VLC (إعادة صياغتها)
- مدة المشروع:
- المدة العادية (3 أشهر)
وصف المشروع
تجريدي
صُممت وثائق المستخدم لمساعدة المستخدمين النهائيين على استخدام منتج أو خدمة. وثائق المستخدم الجيدة مهمة جدًا لأنها توفر وسيلة للمستخدمين لتعلم كيفية استخدام البرنامج وميزاته ونصائحه وحيله وأيضًا حل المشكلات الشائعة التي واجهتها عند استخدام البرنامج. كما أنه يقلل من تكاليف الدعم، كما أنه جزء من هوية الشركة للمنتج: فالتوثيق الجيد للمستخدم هو علامة على سلامة المنتج، أي فريق المطورين.
بدون وثائق مستخدم جيدة، قد لا يعرف المستخدم كيفية القيام بالأشياء المذكورة أعلاه بفعالية وكفاءة. يمكن لوثائق المستخدم أن تلعب دورًا محوريًا في ضمان نجاح المنتج لأن التواصل الرائع يكون ولا يزال دائمًا هو صميم أي عمل أو منتج، والوثائق الرائعة تأخذ هذا التواصل وتضعه في إطار عمل يمكن إدارته يمكن للجميع الوصول إليه لتحقيق النجاح.
في وقت كتابة هذا التقرير، تم الوصول إلى مستندات مستخدم VLC 4634065 مرة وتم تنزيل مشغّل وسائط VLC بمعدل 23 مليون مرة تقريبًا كل شهر من الموقع الإلكتروني الرئيسي، وهذا يبيّن أن الكثير من الأشخاص حول العالم يستخدمون مشغّل الوسائط VLC ويريدون قراءة مستندات المستخدم للحصول على إرشادات حول كيفية استخدام مشغّل الوسائط. في المقابل، إنّ وثائق مستخدم مشغّل الوسائط VLC قديمة وغير مكتملة حاليًا (تم آخر تعديل لها في 28 تشرين الأول (أكتوبر) 2015) ويريد منتدى VideoLAN استخدام هذا المشروع لتحسين مستندات المستخدمين الخاصة به لتمكين المستخدمين النهائيين من الاستمتاع بتجربة سلسة عند استخدام مشغّل وسائط VLC.
الحالة الحالية
في الوقت الحالي، تتوفر وثائق المستخدم على صفحة wiki. المستند قديم أو غير مكتمل أو يصعب التنقل فيه أو العثور على معلوماته ولا يشمل معلومات حول الإصدار الحالي من مشغّل الوسائط ولا يمكن ترجمته إلى اللغة الألمانية، ما يسبّب تراجعًا كبيرًا للأشخاص الذين لا يستطيعون قراءة اللغة الإنجليزية.
لماذا تم تحسين عملية توثيق المستخدمين المقترَحة لي مقارنةً بتوثيقها الحالي؟
ستتم هيكلة وثائق المستخدم المقترحة لتحسين وضمان الكفاءة والاتساق وراحة البال للمستخدم النهائي. ستتضمّن الدورة أدلة مكتوبة وصورًا مرتبطة بها، وستتضمّن إرشادات وشرحًا حول كيفية استخدام كل ميزة من ميزات مشغّل الوسائط VLC، بالإضافة إلى تحديث المحتوى وتسهيل تصفّحه واستيعابه وترجمته إلى خمس لغات رئيسية على الأقل.
الموجهون: جان باتيست، أليكس، سيمون
التحليل
أجرينا محادثة مع "جان بابتيست" حول البيئة الجديدة التي سيتم نقل مستندات المستخدم الحالية إليها لإجراء تحسينات، وقد شارك رابطان يعرضان مستودع Gitlab للملف المصدر المكتوب باستخدام Sphinx والوثائق الرئيسية المستضافة على تطبيق "قراءة المستندات"، وقال إنّهم يتوقعون أن تكون المستندات الجديدة مشابهة لها. لقد بحثت كثيرًا عن هذه الأدوات لكي أفهم بشكل أفضل طريقة عملها.
أبو الهول
يعتبر Sphinx حلاً قويًا ومتقنًا لتوثيق البرامج. ويشمل هذا البرنامج عددًا من الميزات التي يتوقعها المؤلفون، مثل النشر من مصدر واحد وإعادة استخدام المحتوى من خلال تضمين المحتوى الشرطي وتضمينه استنادًا إلى نوع المحتوى والعلامات، بالإضافة إلى العديد من مواضيع HTML الناضجة التي تقدّم تجربة مستخدم رائعة على الأجهزة الجوّالة وأجهزة الكمبيوتر المكتبي، والإشارة إلى الصفحات والمستندات والمشاريع دعم الفهرس ومسرد المصطلحات ودعم النشر على نطاق عالمي. وتستخدم هذه الإضافة أيضًا reOrganizationText كلغة ترميزية، وتأتي العديد من نقاط قوتها من خلال إمكانات reOrgText والاستقلالية فيها وقدرتها على ترجمة المستندات.
قراءة المستندات
تعمل "مستندات Google" على تبسيط مستندات البرامج من خلال إنشاء المستندات تلقائيًا وتحديد إصداراتها واستضافتها نيابةً عنك. لا تتزامن هذه الأداة أبدًا، بمعنى أنه كلما دفعت رمزًا برمجيًا إلى نظام التحكم في الإصدار المفضل لديك، سواء كان Git أو Mercurial أوبازار أو Subversion، سينشئ تطبيق Read the Docs تلقائيًا مستنداتك بحيث يتم تحديث الكود والوثائق باستمرار. يحتوي على إصدارات متعددة؛ حيث يمكن لمحرّر المستندات استضافة وإنشاء إصدارات متعددة من المستندات بحيث يكون استخدام نسخة 1.0 من المستندات وإصدار 2.0 أمرًا سهلاً كوجود فرع أو علامة منفصلة في نظام التحكم في الإصدار. قراءة المستندات مجانية ومفتوحة المصدر وتستضيف وثائق لما يقرب من 100000 مشروع مفتوح المصدر كبير وصغير في كل لغة بشرية وكمبيوتر تقريبًا.
المصدر
Sphinx هي أداة فعالة بشكل كبير، كما أن "قراءة المستندات" يتم إنشاؤها فوقها لتوفير استضافة مستندات Sphinx، مما يجعل مستنداتك محدَّثة على جميع الإصدارات. وكلاهما يمثلان مجموعة رائعة من الأدوات التي يمكن للمطورين والكتاب التقنيين استخدامها لإنشاء وثائق المستخدم التي ستكون الأفضل للمستخدمين النهائيين.
يدعم Sphinx ترجمة الوثائق إلى لغات متعددة. وهي تتيح التحكم في الإصدار الذي سيتم استخدامه لإدارة الوثائق. على عكس موقع wiki الحالي الذي يمكن لأي شخص فيه تحرير المعلومات الصحيحة وعدم إضافتها، سيضمن نظام التحكم في الإصدار هذا مراجعة كافة التغييرات أولاً قبل دمجها في المستودع الرئيسي. كما أن التحكم في الإصدار سيجعل الوثائق تزيد من مساهمة البرامج المفتوحة المصدر في المشروع لأنه يمكن للأشخاص إنشاء مشكلات وفتح طلبات السحب وما إلى ذلك. ويتم استخدام أداة Sphinx وقراءة المستندات من خلال قائمة من المنتديات الأخرى الرائعة مثل 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/
بنية التوثيق المقترح
لقد أنشأتُ بنية لمستندات مستخدمي VLC والتي يمكن العثور عليها هنا: https://docs.google.com/document/d/1Sy2V2IADoCyfnGBK70v8mkjiWK2tH-oWdUlDxAfQAYA/edit?usp=sharing. قبل بدء تنفيذ هذا الهيكل الجديد، يجب أن يوافق عليه الموجهون. هذا يعني أنه من المحتمل أن يتغير الهيكل بعد أن يراجعه المرشدون.
أهداف المشروع
- إعادة هيكلة الوثائق.
- عدِّل المستندات لتلائم الإصدارات الحديثة من VLC.
- انقل وثائق المستخدم إلى Gitlab باستخدام Sphinx وReadthe Docs.
- إزالة الصور والمعلومات القديمة
- أعد كتابة مستندات المستخدم لتسهيل فهمها.
- أعده للترجمة باستخدام تدويل Sphinx.
- اجعل منتدى التوثيق يعمل حتى يتمكن المستخدمون من الإبلاغ عن أي مشاكل تمت مواجهتها أثناء قراءة الوثائق أو حلها.
لماذا هذا المشروع؟
كان لديّ اعتقاد دائمًا بأنّ كتابة الرموز وحلّ المشاكل وإنشاء البرامج يمكن تحقيق أقصى إمكاناتها عندما تتوفّر لك أيضًا القدرة على تثقيف الآخرين حول هذا الموضوع من خلال الكتابة. على الصعيد الشخصي، كنت منبهرًا دائمًا بالجهود التي يبذلها مجتمع VideoLAN في إنشاء حلول برمجية مجانية للوسائط المتعددة. عندما كنت طفلاً، لم يكن مشغّل الوسائط VLC هو البرنامج الذي أستخدمه للاستماع إلى الموسيقى أو مشاهدة الأفلام لأنّه كان بصوت عالٍ للغاية ويتضمّن الكثير من الميزات. ويشرّفني العمل مع المنتدى الذي ساهم في جعل طفولتي رائعة.
لماذا أنا الشخص المناسب لهذا المشروع؟
أعتقد أنني الشخص المناسب لهذا المشروع لأن:
- لدي خبرة سابقة في تحسين وثائق المؤسسات ويمكنني استخدام أي نظام للتحكم في الإصدار، لذا لن يكون تنفيذ الأوامر في Gitab مشكلةً. علاوة على ذلك، ما يدفعني هو العمل في المشروعات التي تخلق قيمة للأشخاص.
- أعتقد أنه إذا كنت تريد أن يقوم شخص ما بشيء ما بأكثر الطرق فعالية ممكنة، فعليك توثيقه. من خلال توثيق عملياتك، فإنك تضمن الكفاءة والاتساق وراحة البال لأي شخص مشارك.
- أعرف احتياجات مستخدمي VLC لأنني واحد منهم. سيتيح ذلك كتابة الوثائق بطريقة يفهمها كل مستخدم آخر في جميع أنحاء العالم للوهلة الأولى.