Project VLC

Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season Dokumen.

Ringkasan proyek

Organisasi open source:
VLC
Penulis teknis:
Abhishek Pratap Singh
Nama proyek:
Lanjutkan Modernisasi dokumentasi pengguna VLC
Durasi proyek:
Durasi standar (3 bulan)

Project description

STATUS DOKUMENTASI SAAT INI

Dokumentasi Pengguna VLC sedang dalam proses modernisasi dan pembaruan. Transisi sedang berlangsung untuk beralih dari dokumentasi lama berbasis wiki[1] ke dokumentasi pengguna modern yang dibuat sphinx[2] yang dihosting di ReadTheDocs.

TARGET AUDIENS

Target audiensnya adalah pengguna yang penasaran dan ingin menjelajahi fitur pemutar media VLC di luar pemutar media biasa, dan sampai batas tertentu, hal ini juga akan membantu developer dengan berfungsi sebagai panduan referensi yang mudah. Oleh karena itu, saya berencana untuk menyertakan instruksi berbasis GUI (beserta gambar jika relevan) dan metode berbasis CLI (beserta cuplikan kode) sehingga pengguna akhir bebas memilih.

Saya percaya bahwa bahasa dokumentasi (terutama bagian GUI) harus dipersingkat sehingga seseorang dengan pemaparan nominal ke komputer operasi akan dapat memahami dan menerapkan panduan ini. Di sisi lain, tidak boleh terlalu panjang atau memberikan penjelasan (terutama bagian CLI) sehingga para pembuat kode tidak akan tertarik.

Keseimbangan yang tepat dapat dicapai dengan menyebutkan prasyarat di awal halaman atau mempertahankan bagian opsional yang dapat dilewati dengan baik.

Untuk membuat terjemahan, target audiensnya adalah pengembang/pengguna VLC dengan pemahaman bahasa Inggris yang baik dan bahasa yang akan mereka terjemahkan.

ALAT

Dokumentasi baru sedang dibuat oleh Sphinx dan dihosting di ReadTheDocs, dan sistem kontrol versi diimplementasikan di GitLab. Saya memiliki beberapa pengalaman menggunakan Git dan GitHub, yang membantu saya memahami GitLab, meskipun ada beberapa fitur berbeda yang membutuhkan waktu untuk dipelajari.

Sedangkan untuk Sphinx, saya pernah membaca tentang hal itu ketika sesama penggemar {i>open source<i} telah mengatakan berapa banyak organisasi yang menggunakannya untuk membangun dokumentasi mereka (dengan contoh terkenal Blender, yang menggunakan Sphinx untuk membangun Panduan Pengguna [3] dan dokumentasi API mereka [4]).

Saya sedikit familier dengan ReadTheDocs, yang merupakan alat yang baik untuk pembuatan versi dan untuk menghosting dokumentasi teknis. Karena itu, saya dapat membuat dokumentasi VLC tanpa banyak masalah dan sudah familier dengan reStructured Text, format yang digunakan.

Untuk terjemahan, VLC menggunakan Babel untuk menghasilkan file .po untuk mengimplementasikan i18n dan l10n. Saat ini, saya sudah memahami alur kerja Babel dan cara membuat file .mo menggunakan Sphinx.

Saya bermaksud menggunakan periode bonding untuk lebih memahami seluk-beluk alat yang disebutkan di atas.

PENGIRIMAN DAN LINIMASA MINGGUAN

Sebagai bagian dari proyek 2019, bagian dari Penginstalan, Antarmuka, Audio, Video, Pemutaran, dll. (sebagian besar fungsi dasar) sudah dibahas. Oleh karena itu, untuk project 2020, saya ingin memperbarui dan mengerjakan bagian penggunaan lanjutan di dokumentasi Pengguna.

PENGIRIMAN 1 [Week1-2]: Memperbarui Dokumentasi Transcode, seperti yang disebutkan dalam #7[5].

  • Transcoding
  • Melakukan transcoding Beberapa Video
  • Tambahkan logo
  • Gabungkan video
  • Mengekstrak Audio dan Mengekstrak audio dari file
  • Potong DVD

DELIVERABLE 2 [Minggu 3-4]: Memperbarui Menggunakan VLC sebagai plugin web[6], saat menguji di Firefox 77, Chrome 83, dan Edge 83.

  • Membuat halaman web dengan video
  • Menyematkan atribut tag
  • Deskripsi JavaScript API

PENGIRIMAN 3 [Minggu 5]: Uji perintah Antarmuka Baris Perintah [7] dan perbarui sesuai dengan itu.

  • Streaming
  • Pemilihan modul
  • Opsi Spesifik Per Item
  • Filter

Minggu ke-6: Minggu Buffering untuk tiga hasil di atas.

PENGIRIMAN 4 [Minggu 7-8]: Bersiap untuk terjemahan. Selain memperbarui, saya akan menyiapkan terjemahan ke dalam bahasa lain. Hal ini penting karena setelah penerjemahan, pengguna yang tidak memiliki latar belakang bahasa Inggris dapat membaca dokumentasinya (dan, sebagai catatan, VLC akan menjadi selangkah lebih dekat untuk mencapai Dominasi Dunia[8]).

Seperti disebutkan di bagian Alat dalam proposal, saat ini VLC menggunakan Babel untuk menghasilkan file .po untuk terjemahan. Saya akan mendokumentasikan proses bagi pengguna/sukarelawan untuk:

  • Mendownload dan membuat dokumentasi dasar secara lokal.
  • Gunakan Babel untuk menghasilkan file yang diperlukan.
  • Masukkan Terjemahan untuk string.
  • Membuat dokumentasi terjemahan menggunakan Sphinx.
  • Commit perubahan.

PENGIRIMAN 5 [Minggu 9-10]: Bersiap untuk dokumentasi modul. Seperti yang telah didiskusikan dengan para mentor, saya berencana mempersiapkan dokumentasi modul dalam dua bagian.

Bagian - I: Membuat file di dekat modul melalui skrip yang mencari opsi valid dari code base dan mengekstrak penggunaan satu baris (dan nilai default) dari halaman wiki yang sesuai. Hal ini akan berfungsi sebagai draf dasar.

Bagian - II: Membangun struktur khusus platform yang menautkan semua modul+plugin+opsi untuk platform tertentu (Windows, dan jika waktu memungkinkan, untuk Fedora).

Membuat file di dekat modul akan memastikan bahwa dokumentasi dekat dengan kode sumber. Dengan menggunakan pendekatan {i>bottom-top<i}, Dokumentasi Modul utama akan dibuat dengan menggabungkan {i>file<i} yang dibuat di Bagian - I dan menggunakan struktur yang dibuat di Bagian - II sebagai referensi.

File yang dibuat melalui otomatisasi memerlukan peninjauan, tetapi prioritas pertama adalah membuat framework yang fungsional. Setelah itu tercapai, dan sesuai waktu yang tersedia, saya akan meninjau file tersebut untuk memverifikasi opsinya. Framework ini diprioritaskan karena setelah tersedia, developer dan pengelola juga dapat mulai berkontribusi dengan menambahkan kasus penggunaan yang relevan.

BONUS PENGIRIMAN [Minggu ke-11]: Bersiaplah untuk rilis versi 4.0. Jika proyek tetap sesuai jadwal, saya ingin mengusulkan {i>deliverable<i} bonus. Seperti yang didiskusikan dengan para mentor, mempersiapkan rilis 4.0 menyiratkan memiliki dokumentasi yang stabil dan hampir lengkap untuk versi 3.0.

Oleh karena itu, saya akan mempelajari dokumentasi yang sudah selesai di bagian berikut untuk memverifikasi dan memperbarui metode yang disebutkan:

  • Penggunaan Dasar: Media, Pemutaran, Audio, Video, Subtitel, Hotkey, Rekaman, Setelan, Tips & Trik.
  • Penggunaan Lanjutan: Pemutar, Antarmuka, Transcode, Streaming, Kasus yang Tidak Biasa.
  • Add-on: Ekstensi, Skin.

Minggu ke-12: Minggu Buffering untuk tiga hasil di atas + Laporan Akhir.

MENGAPA SAYA JADI ORANG YANG TEPAT UNTUK PROJECT INI?

Sebagai penggemar teknologi, saya memiliki pengalaman menggunakan/menguji perangkat lunak dan kadang-kadang, mencoba memahami basis kode mereka. Sebenarnya, mencoba memahami basis kode organisasi {i>open-source<i} adalah pertama kalinya saya benar-benar menyadari pentingnya dokumentasi. Selain itu, sebagai penggemar musik, saya memiliki banyak pengalaman menyesuaikan diri dengan VLC :)

Terlepas dari itu, saya telah menjadi peneliti dan penulis sepanjang hidup saya. Jika saya tidak menulis sesuatu, saya tidak pernah benar-benar memahaminya, dan kebiasaan ini menjadikan saya seorang pencatat dan pendokumentasi yang efisien.

Persimpangan dari kedua kebiasaan ini membuat saya cocok untuk dokumentasi teknis. Saya dapat menemukan aspek teknis sekaligus mendokumentasikan temuan/proses saya dengan cara yang dipahami pengguna.

Link: [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.bwiki.org/api/current/index.html [5] https://docs.blender.org/manual/en/latest/ [4] https://docs.bwiki.org/api/current/index.html [5] https://docs.blender.org/manual/en/latest/