این صفحه حاوی جزئیات یک پروژه نگارش فنی است که برای فصل اسناد Google پذیرفته شده است.
خلاصه پروژه
- سازمان منبع باز:
- VLC
- نویسنده فنی:
- آبیشک پراتاپ سینگ
- نام پروژه:
- به مدرن سازی مستندات کاربر VLC ادامه دهید
- طول پروژه:
- طول استاندارد (3 ماه)
شرح پروژه
وضعیت فعلی اسناد
مستندات کاربر VLC در مرحله مدرن سازی و به روز رسانی است. انتقال از اسناد قدیمی‌تر مبتنی بر ویکی[1] به مستندات کاربر مدرن ساخته شده از ابوالهول[2] که در ReadTheDocs میزبانی می‌شود، در حال انجام است.
مخاطبان هدف
مخاطب هدف هم کاربر کنجکاویی است که می‌خواهد ویژگی‌های پخش‌کننده رسانه VLC را فراتر از یک پخش‌کننده رسانه معمولی کشف کند، و هم تا حدی با ارائه یک راهنمای مرجع آسان، به توسعه‌دهندگان نیز کمک خواهد کرد. از این رو، من قصد دارم دستورالعمل‌های مبتنی بر رابط کاربری گرافیکی (همراه با تصاویر در صورت لزوم) و روش‌های مبتنی بر CLI (همراه با تکه‌های کد) را لحاظ کنم تا کاربر نهایی آزادی انتخاب داشته باشد.
من معتقدم که زبان اسناد (به ویژه بخش رابط کاربری گرافیکی) باید به قدری کمرنگ شود که فردی با قرار گرفتن در معرض اسمی با رایانه های عامل بتواند راهنما را درک و اجرا کند. از طرف دیگر، نباید زیاد طولانی یا توضیحی باشد (مخصوصاً بخش CLI) که کدنویس ها علاقه خود را از دست می دهند.
تعادل مناسب را می توان با ذکر پیش نیازها در ابتدای صفحه یا حفظ بخش های اختیاری که افراد متبحر می توانند نادیده بگیرند، به دست آورد.
برای ساختن ترجمه ها، مخاطبان هدف توسعه دهندگان/کاربران VLC با درک خوب از زبان انگلیسی و زبانی هستند که می خواهند به آن ترجمه کنند.
ابزار
مستندات جدید توسط Sphinx ساخته شده و در ReadTheDocs میزبانی می شود و سیستم کنترل نسخه در GitLab پیاده سازی شده است. من تجربه‌ای در گذشته با استفاده از Git و GitHub داشته‌ام، که به من کمک کرد تا از GitLab استفاده کنم، اگرچه ویژگی‌های مختلفی وجود داشت که یادگیری آنها مدتی طول کشید.
در مورد Sphinx، زمانی در مورد آن خوانده بودم که یکی از علاقه مندان به منبع باز اشاره کرده بود که چند سازمان از آن برای ساخت اسناد خود استفاده می کنند (به عنوان مثال قابل توجه Blender، که از Sphinx برای ساختن کتابچه راهنمای کاربر[3] و اسناد API خود استفاده می کند. [4]).
من کمی با ReadTheDocs آشنا بودم که ابزار خوبی برای نسخه سازی و میزبانی اسناد فنی است. از این رو، من توانستم اسناد VLC را بدون مشکل بسازم و با قالب بندی استفاده شده از متن بازسازی شده آشنا هستم.
برای ترجمه، VLC از Babel برای تولید فایل های .po به منظور پیاده سازی i18n و l10n استفاده می کند. در حال حاضر، من با گردش کار Babel و نحوه ساخت فایل‌های .mo با استفاده از Sphinx آشنا هستم.
من قصد دارم از دوره باندینگ برای آشنایی بیشتر با پیچیدگی های ابزارهای ذکر شده در بالا استفاده کنم.
موارد تحویل و جدول زمانی هفتگی
به عنوان بخشی از پروژه 2019، بخش هایی از نصب، رابط، صدا، تصویر، پخش و غیره (بیشتر قابلیت های اساسی) قبلاً پوشش داده شده است. از این رو، برای پروژه 2020، من می خواهم بخش استفاده پیشرفته از اسناد کاربر را به روز کنم و روی آن کار کنم.
قابل تحویل 1 [هفته 1-2]: اسناد Transcode را به روز کنید، همانطور که در شماره 7 [5] ذکر شد.
- رمز عبور
- رمزگذاری چندین ویدیو
- یک لوگو اضافه کنید
- ویدیوها را با هم ادغام کنید
- استخراج صدا و استخراج صدا از یک فایل
- یک دی وی دی را ریپ کنید
تحویل 2 [هفته 3-4]: با استفاده از VLC به عنوان یک افزونه وب[6]، در حالی که در فایرفاکس 77، کروم 83 و اج 83 آزمایش می کنید، به روز رسانی کنید.
- ساخت صفحات وب با ویدئو
- تعبیه ویژگی های برچسب
- توضیحات JavaScript API
قابل تحویل 3 [هفته 5]: دستورات Command Line Interface[7] را آزمایش کنید و بر اساس آن به روز رسانی کنید.
- جریان ها
- انتخاب ماژول ها
- گزینه های خاص مورد
- فیلترها
هفته 6: هفته بافر برای سه محصول فوق.
تحویل 4 [هفته 7-8]: برای ترجمه ها آماده شوید. جدا از به روز رسانی، برای ترجمه به زبان های دیگر آماده خواهم شد. این مهم است زیرا پس از ترجمه، کاربران بدون پیشینه انگلیسی می‌توانند اسناد را بخوانند (و در یک یادداشت جانبی، VLC یک گام نزدیک‌تر برای دستیابی به سلطه جهانی است[8]).
همانطور که در بخش ابزارهای پیشنهاد ذکر شد، VLC در حال حاضر از Babel برای تولید فایل های .po برای ترجمه ها استفاده می کند. من روند را برای یک کاربر/داوطلب مستند خواهم کرد تا:
- مستندات پایه را به صورت محلی دانلود و بسازید.
- از Babel برای تولید فایل های مورد نیاز استفاده کنید.
- ترجمه ها را برای رشته ها وارد کنید.
- ساخت اسناد ترجمه شده با استفاده از Sphinx.
- تغییرات را متعهد شوید.
قابل تحویل 5 [هفته 9-10]: برای مستندسازی ماژول ها آماده شوید. همانطور که با مربیان صحبت شد، من قصد دارم برای مستندات ماژول ها در دو بخش آماده کنم.
بخش - اول: ایجاد فایل‌های نزدیک به ماژول‌ها از طریق اسکریپتی که به دنبال گزینه‌های معتبر از پایه کد می‌گردد و استفاده یک خطی (و مقادیر پیش‌فرض) آنها را از صفحات ویکی مربوطه استخراج می‌کند. این به عنوان یک پیش نویس اساسی عمل می کند.
بخش - دوم: ساختن یک ساختار مخصوص پلتفرم که همه ماژول‌ها+افزونه‌ها+گزینه‌ها را برای یک پلتفرم خاص (ویندوز و اگر زمان اجازه دهد، برای فدورا نیز) به هم پیوند می‌دهد.
ایجاد فایل‌ها در نزدیکی ماژول‌ها اطمینان حاصل می‌کند که اسناد به کد منبع نزدیک هستند. با استفاده از رویکرد پایین به بالا، مستندات اصلی ماژول ها از ترکیب فایل های ساخته شده در قسمت اول و با استفاده از ساختار ساخته شده در قسمت دوم به عنوان مرجع ساخته می شود.
فایل‌های ایجاد شده از طریق اتوماسیون نیاز به بررسی دارند، اما اولین اولویت ایجاد یک چارچوب کاربردی است. پس از رسیدن به آن، و در زمان موجود، فایل ها را برای بررسی گزینه ها بررسی می کنم. این چارچوب در اولویت قرار دارد زیرا پس از در دسترس قرار گرفتن، توسعه‌دهندگان و نگهدارنده‌ها نیز می‌توانند با افزودن موارد استفاده مرتبط شروع به مشارکت کنند.
پاداش تحویلی [هفته 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