Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season of Docs.
Ringkasan project
- Organisasi open source:
- VLC
- Penulis teknis:
- Abhishek Pratap Singh
- Nama project:
- Melanjutkan Modernisasi dokumentasi pengguna VLC
- Durasi project:
- 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 dibangun sphinx[2] yang dihosting di ReadTheDocs.
TARGET AUDIENS
Audiens target adalah pengguna yang ingin menjelajahi fitur pemutar media VLC di luar pemutar media biasa, dan sampai batas tertentu, panduan ini juga akan membantu developer dengan berfungsi sebagai panduan referensi yang mudah. Oleh karena itu, saya berencana untuk menyertakan instruksi berbasis GUI (bersama dengan gambar jika relevan) dan metode berbasis CLI (bersama dengan cuplikan kode) sehingga pengguna akhir memiliki kebebasan memilih.
Saya yakin bahwa bahasa dokumentasi (terutama bagian GUI) harus dipersingkat agar orang yang sedikit memahami komputer operasi akan dapat memahami dan menerapkan panduan ini. Di sisi lain, dokumen tidak boleh terlalu panjang atau menjelaskan (terutama bagian CLI) sehingga coder kehilangan minat.
Keseimbangan yang tepat dapat dicapai dengan menyebutkan prasyarat di awal halaman atau mempertahankan bagian opsional yang dapat dilewati oleh pengguna yang sudah berpengalaman.
Untuk membuat terjemahan, target audiensnya adalah developer/pengguna VLC yang memiliki pemahaman yang baik tentang bahasa Inggris dan bahasa yang akan diterjemahkan.
ALAT
Dokumentasi baru sedang dibuat oleh Sphinx dan dihosting di ReadTheDocs, serta sistem kontrol versi diterapkan di GitLab. Saya memiliki beberapa pengalaman sebelumnya dalam menggunakan Git dan GitHub, yang membantu saya memahami GitLab, meskipun ada beberapa fitur berbeda yang perlu waktu untuk dipelajari.
Untuk Sphinx, saya telah membacanya saat sesama penggemar open source menyebutkan betapa banyak organisasi yang menggunakannya untuk membuat dokumentasi (dengan contoh yang terkenal dari Blender, yang menggunakan Sphinx untuk membuat Panduan Pengguna[3] dan dokumentasi API[4]).
Saya sedikit memahami ReadTheDocs, yang merupakan alat yang bagus untuk pembuatan versi dan hosting dokumentasi teknis. Oleh karena itu, saya dapat membuat dokumentasi VLC tanpa banyak masalah dan sudah terbiasa dengan reStructured Text, format yang digunakan.
Untuk terjemahan, VLC menggunakan Babel untuk membuat file .po guna menerapkan i18n dan l10n. Saat ini, saya membiasakan diri dengan alur kerja Babel dan cara membuat file .mo menggunakan Sphinx.
Saya ingin menggunakan periode ikatan untuk lebih memahami seluk-beluk alat yang disebutkan di atas.
OUTPUT DAN LINIMASA MINGGUAN
Sebagai bagian dari project 2019, bagian Instalasi, Antarmuka, Audio, Video, Pemutaran, dll. (sebagian besar fungsi dasar) sudah tercakup. Oleh karena itu, untuk project tahun 2020, saya ingin memperbarui dan mengerjakan bagian penggunaan lanjutan dalam dokumentasi Pengguna.
OUTPUT 1 [Minggu 1-2]: Memperbarui Dokumentasi Transcode, seperti yang disebutkan di #7[5].
- Transcode
- Lakukan transcoding pada Beberapa Video
- Tambahkan logo
- Gabungkan video menjadi satu
- Mengekstrak Audio dan Mengekstrak audio dari file
- Menyalin DVD
OUTPUT 2 [Minggu 3-4]: Memperbarui Penggunaan 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
OUTPUT 3 [Minggu 5]: Uji perintah Antarmuka Command Line[7] dan perbarui sesuai kebutuhan.
- Streaming
- Pemilihan modul
- Opsi Khusus Item
- Filter
Minggu ke-6: Minggu Buffer untuk tiga hasil di atas.
OUTPUT 4 [Minggu 7-8]: Bersiaplah untuk penerjemahan. Selain mengupdate, saya akan mempersiapkan terjemahan ke bahasa lain. Hal ini penting karena setelah terjemahan, pengguna yang tidak memiliki latar belakang bahasa Inggris akan dapat membaca dokumentasi (dan, sebagai catatan tambahan, VLC akan selangkah lebih dekat untuk mencapai World Domination[8]).
Seperti yang disebutkan di bagian Alat dalam proposal, VLC saat ini menggunakan Babel untuk membuat file .po untuk terjemahan. Saya akan mendokumentasikan proses bagi pengguna/relawan untuk:
- Download dan build dokumentasi dasar secara lokal.
- Gunakan Babel untuk membuat 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 dibahas dengan mentor, saya berencana untuk menyiapkan dokumentasi modul dalam dua bagian.
Bagian - I: Membuat file di dekat modul melalui skrip yang mencari opsi yang valid dari code base dan mengekstrak penggunaan satu barisnya (dan nilai default) dari halaman wiki terkait. Ini akan berfungsi sebagai draf dasar.
Bagian - II: Mem-build struktur khusus platform yang menautkan semua modul+plugin+opsi untuk platform tertentu (Windows, dan jika waktu memungkinkan, juga untuk Fedora).
Membuat file di dekat modul akan memastikan bahwa dokumentasi berada di dekat kode sumber. Dengan menggunakan pendekatan bottom-top, Dokumentasi Modul utama akan dibuat dari penggabungan file 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 fungsional. Setelah itu, dan sesuai dengan waktu yang tersedia, kami akan meninjau file untuk memverifikasi opsi tersebut. Framework ini diprioritaskan karena setelah tersedia, developer dan pengelola juga dapat mulai berkontribusi dengan menambahkan kasus penggunaan yang relevan.
OUTPUT BONUS [Minggu 11]: Bersiaplah untuk rilis 4.0. Jika project tetap sesuai jadwal, saya ingin mengusulkan hasil kerja bonus. Seperti yang dibahas dengan mentor, mempersiapkan rilis 4.0 berarti memiliki dokumentasi yang stabil dan hampir lengkap untuk versi 3.0.
Oleh karena itu, saya akan membahas dokumentasi yang telah 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, Transcoding, Streaming, Kasus Tidak Biasa.
- Add-on: Ekstensi, Skin.
Minggu ke-12: Minggu Buffer untuk tiga hasil di atas + Laporan Akhir.
MENGAPA SAYA ORANG YANG TEPAT UNTUK PROJEK INI?
Sebagai penggemar teknologi, saya memiliki pengalaman dalam menggunakan/menguji software dan terkadang, mencoba memahami code base-nya. Faktanya, mencoba memahami code base organisasi open source adalah pertama kalinya saya benar-benar menyadari pentingnya dokumentasi. Selain itu, sebagai penggemar musik, saya memiliki banyak pengalaman dalam menyesuaikan VLC :)
Selain itu, saya telah menjadi peneliti dan penulis sepanjang hidup saya. Kecuali saya menuliskan sesuatu, saya tidak pernah benar-benar memahaminya, dan kebiasaan ini telah menjadikan saya pencatat dan dokumentasi yang efisien.
Perpaduan kedua kebiasaan ini yang membuat saya cocok untuk dokumentasi teknis. Saya dapat menemukan cara untuk memahami aspek teknis beserta mendokumentasikan temuan/proses saya dengan cara yang dapat 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.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