پروژه VideoLAN

این صفحه حاوی جزئیات یک پروژه نگارش فنی است که برای فصل اسناد Google پذیرفته شده است.

خلاصه ی پروژه

سازمان منبع باز:

VideoLAN

نویسنده فنی:

ادیدیونگ آنی آسیکپو

نام پروژه:

اسناد کاربر VLC را مدرن کنید (بازنویسی کنید).

طول پروژه:

طول استاندارد (3 ماه)

شرح پروژه

خلاصه

مستندات کاربر برای کمک به کاربران نهایی برای استفاده از یک محصول یا خدمات طراحی شده است. مستندات خوب کاربر بسیار مهم است زیرا راهی را برای کاربران فراهم می کند تا نحوه استفاده از یک نرم افزار، ویژگی ها، نکات، ترفندهای آن را بیاموزند و همچنین مشکلات رایجی که هنگام استفاده از نرم افزار با آن مواجه می شوند را حل کنند. همچنین هزینه پشتیبانی را کاهش می دهد و بخشی از هویت شرکتی محصول است: مستندات کاربر خوب نشانه سالم بودن محصول، تیم توسعه دهنده است.

بدون مستندات کاربر خوب، کاربر ممکن است نداند که چگونه کارهای فوق را به طور موثر و کارآمد انجام دهد. مستندات کاربر می تواند نقشی اساسی در تضمین موفقیت یک محصول داشته باشد زیرا ارتباطات عالی همیشه در قلب هر کسب و کار یا محصولی وجود دارد و خواهد بود و یک سند عالی فقط آن ارتباط را می گیرد و آن را در یک چارچوب قابل مدیریت قرار می دهد که همه می توانند برای موفقیت به آن دسترسی داشته باشند.

در زمان نگارش این مقاله، اسناد کاربر VLC 4,634,065 بار مشاهده شده است و پخش کننده رسانه VLC تقریباً 23 میلیون بار در هر ماه از وب سایت اصلی دانلود می شود، این نشان می دهد که افراد زیادی در سراسر جهان از VLC Media استفاده می کنند. Player و ممکن است بخواهد اسناد کاربر خود را برای راهنمایی در مورد نحوه استفاده از پخش کننده رسانه بخوانید. با این حال، مستندات کاربر VLC مدیا پلیر در حال حاضر قدیمی و ناقص است (آخرین بار در 28 اکتبر 2015 اصلاح شد) و جامعه VideoLAN می‌خواهد از این پروژه برای بهبود مستندات کاربری خود استفاده کند تا کاربران نهایی بتوانند تجربه‌ای یکپارچه داشته باشند. با استفاده از پخش کننده رسانه VLC

وضعیت فعلی

در حال حاضر، اسناد کاربر در یک صفحه ویکی موجود است. منسوخ، ناقص، ناوبری یا یافتن اطلاعات سخت است، اطلاعات مربوط به نسخه فعلی پخش کننده رسانه را پوشش نمی دهد و فقط می تواند به دویچ ترجمه شود که باعث شکست بزرگی برای افرادی می شود که نمی توانند زبان انگلیسی را بخوانند.

چرا اسناد کاربر پیشنهادی من نسبت به سند فعلی بهبود یافته است؟

مستندات کاربر پیشنهادی برای بهبود و اطمینان از کارایی، سازگاری و آرامش خاطر برای کاربر نهایی ساختاربندی خواهد شد. این شامل راهنماهای مکتوب و تصاویر مرتبط با آن، شامل دستورالعمل ها و توضیح در مورد نحوه استفاده از هر ویژگی پخش کننده رسانه VLC، به روز، آسان برای پیمایش، قابل فهم و ترجمه حداقل به پنج زبان اصلی است.

مربیان: ژان باپتیست، الکس، سیمون

تحلیل و بررسی

من و ژان باپتیست در مورد محیط جدیدی که مستندات کاربر فعلی برای بهبود به آن منتقل می شود گفتگو کردیم و او دو پیوند را به اشتراک گذاشت که یک مخزن Gitlab از فایل منبع نوشته شده با Sphinx و اسناد اصلی میزبانی شده در Read the Docs و را نشان می داد. او گفت که انتظار دارند اسناد جدید مشابه آن باشد. من در مورد این ابزارها تحقیق زیادی کردم تا درک بهتری از نحوه کارکرد آن داشته باشم.

ابوالهول

Sphinx یک راه حل قوی و بالغ برای اسناد نرم افزاری است. این شامل تعدادی از ویژگی‌هایی است که نویسندگان انتظار دارند، مانند انتشار یک منبع، استفاده مجدد از محتوا از طریق شامل، شامل مشروط بر اساس نوع محتوا و برچسب‌ها، چندین طرح زمینه HTML بالغ که تجربه کاربری عالی را در تلفن همراه و دسکتاپ ارائه می‌کند، ارجاع به صفحات، اسناد. و پشتیبانی از فهرست و واژه نامه پروژه ها و پشتیبانی بین المللی. همچنین از reStructuredText به عنوان زبان نشانه گذاری خود استفاده می کند و بسیاری از نقاط قوت آن ناشی از قدرت و صریح بودن reStructuredText و توانایی آن در ترجمه اسناد است.

Docs را بخوانید

خواندن Docs با ساخت خودکار، نسخه‌سازی و میزبانی اسناد شما، اسناد نرم‌افزار را ساده می‌کند. هرگز از همگام خارج نمی شود. یعنی هر زمان که کد را به سیستم کنترل نسخه مورد علاقه خود فشار دهید، خواه Git، Mercurial، Bazaar یا Subversion، Read the Docs به طور خودکار اسناد شما را می سازد تا کد و اسناد شما همیشه به روز باشند. چندین نسخه دارد. Read the Docs می‌تواند چندین نسخه از اسناد شما را میزبانی کند و بسازد، بنابراین داشتن یک نسخه 1.0 از اسناد خود و یک نسخه 2.0 از اسناد شما به آسانی داشتن یک شاخه یا برچسب جداگانه در سیستم کنترل نسخه شما است. Read the Docs رایگان و منبع باز است و اسنادی را برای نزدیک به 100000 پروژه منبع باز بزرگ و کوچک تقریباً به هر زبان انسان و رایانه میزبانی می کند.

حکم

Sphinx یک ابزار فوق‌العاده قدرتمند است و Read the Docs برای ارائه میزبانی برای اسناد Sphinx که اسناد شما را در نسخه‌های مختلف به‌روز نگه می‌دارد، در بالا ساخته شده است. آنها با هم مجموعه فوق العاده ای از ابزارها هستند که توسعه دهندگان و نویسندگان فنی می توانند از آنها برای ایجاد اسناد کاربر استفاده کنند که برای کاربران نهایی بهترین باشد.

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/latest/.

ساختار اسناد پیشنهادی

من یک ساختار برای VLC User Documentation ایجاد کردم که در اینجا یافت می شود. https://docs.google.com/document/d/1Sy2V2IADoCyfnGBK70v8mkjiWK2tH-oWdUlDxAfQAYA/edit?usp=sharing . قبل از شروع اجرای این ساختار جدید، باید توسط مربیان تایید شود. این به این معنی است که ساختار احتمالاً پس از بررسی توسط مربیان تغییر می کند.

اهداف پروژه

• اسناد را بازسازی کنید.
• اسناد را برای تناسب با نسخه های مدرن VLC به روز کنید.
• اسناد کاربر را با استفاده از Sphinx و ReadtheDocs به Gitlab منتقل کنید.
• تصاویر و اطلاعات منسوخ را حذف کنید.
• اسناد کاربر را بازنویسی کنید تا درک آن آسان تر شود.
• آن را برای ترجمه با استفاده از Sphinx Internationalization تنظیم کنید.
• جامعه اسناد را به گونه‌ای هدایت کنید که کاربران بتوانند مشکلاتی را که در حین خواندن اسناد با آن مواجه می‌شوند گزارش یا حل کنند.

چرا این پروژه؟

من همیشه این باور را داشتم که نوشتن کد، حل مشکلات و ساختن نرم افزار زمانی به پتانسیل کامل خود می رسد که شما نیز بتوانید از طریق نوشتن، دیگران را در مورد آن آگاه کنید. من شخصاً همیشه مجذوب تلاش‌های جامعه VideoLAN در ایجاد راه‌حل‌های نرم‌افزار رایگان برای چند رسانه‌ای بوده‌ام. در دوران کودکی، پخش کننده رسانه VLC همیشه نرم افزاری بود که هنگام گوش دادن به موسیقی یا تماشای یک فیلم استفاده می کردم، زیرا صدای بسیار بلندی داشت و دارای ویژگی های بسیار زیادی بود. کار کردن با جامعه ای که به عالی کردن دوران کودکی من کمک کرد باعث افتخار خواهد بود.

چرا من شخص مناسب برای این پروژه هستم

من معتقدم که من شخص مناسبی برای این پروژه هستم زیرا:

• من تجربه قبلی در بهبود مستندات سازمان ها را دارم و می توانم از هر سیستم کنترل نسخه استفاده کنم، بنابراین انجام دستورات در گیتاب مشکلی نخواهد داشت. علاوه بر این، چیزی که من را تشویق می کند، کار بر روی پروژه هایی است که برای مردم ارزش ایجاد می کند.
• من معتقدم که اگر می خواهید کسی کاری را به کارآمدترین شکل ممکن انجام دهد، آن را مستند می کنید. با مستندسازی فرآیندهای خود، کارایی، ثبات و آرامش خاطر را برای هر کسی که درگیر است تضمین می کنید.
• من نیازهای کاربران VLC را می دانم زیرا من یکی از آنها هستم. این امکان نوشتن اسناد را به گونه‌ای فراهم می‌کند که هر کاربر دیگر در سراسر جهان در نگاه اول آن را درک کند.