Project VideoLAN

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

Ringkasan project

Organisasi open source:
VideoLAN
Penulis teknis:
Edidiong Anny Asikpo
Nama project:
Memodernisasi (menulis ulang) dokumentasi pengguna VLC
Durasi proyek:
Durasi standar (3 bulan)

Project description

ABSTRACT

Dokumentasi Pengguna dirancang untuk membantu pengguna akhir menggunakan produk atau layanan. Dokumentasi pengguna yang baik sangat penting karena memberikan sarana bagi pengguna untuk mempelajari cara menggunakan software, fitur, tips, trik, dan juga menyelesaikan masalah umum yang dialami saat menggunakan software. Dokumentasi juga mengurangi biaya dukungan dan merupakan bagian dari identitas perusahaan produk: dokumentasi pengguna yang baik adalah indikasi kesehatan produk, sebagai tim developer.

Tanpa dokumentasi pengguna yang baik, pengguna mungkin tidak tahu bagaimana melakukan hal-hal di atas secara efektif dan efisien. Dokumentasi Pengguna dapat memainkan peran penting dalam memastikan keberhasilan produk karena komunikasi yang baik adalah dan akan selalu menjadi inti dari bisnis atau produk apa pun, dan dokumentasi yang baik hanya mengambil komunikasi tersebut dan menempatkannya dalam framework yang mudah dikelola yang dapat diakses oleh semua orang untuk meraih kesuksesan.

Pada saat penulisan ini, dokumentasi pengguna VLC telah diakses 4.634.065 kali dan pemutar media VLC didownload sekitar 23 juta kali setiap bulan dari situs utama. Hal ini menunjukkan bahwa banyak orang di seluruh dunia menggunakan VLC Media Player dan mungkin ingin membaca dokumentasi penggunanya untuk mendapatkan panduan tentang cara menggunakan pemutar media. Namun, dokumentasi pengguna VLC media player saat ini sudah tidak berlaku dan tidak lengkap (terakhir diubah pada 28 Oktober 2015) dan komunitas VideoLAN ingin menggunakan project ini untuk meningkatkan dokumentasi penggunanya agar pengguna akhir dapat memiliki pengalaman yang lancar saat menggunakan VLC media player.

NEGARA SAAT INI

Saat ini, dokumentasi pengguna tersedia di halaman wiki. Sistem ini sudah usang, tidak lengkap, sulit dinavigasi atau ditemukan, tidak mencakup informasi tentang versi media player saat ini dan hanya dapat diterjemahkan dalam bahasa Jerman, sehingga menyebabkan kemunduran besar bagi orang yang tidak dapat membaca Bahasa Inggris.

MENGAPA DOKUMENTASI PENGGUNA YANG SAYA USULKAN ADALAH PENINGKATAN DARI DOKUMENTASI SAAT INI?

Dokumentasi pengguna yang diusulkan akan disusun untuk meningkatkan dan memastikan efisiensi, konsistensi, dan ketenangan bagi pengguna akhir. Panduan ini akan berisi panduan tertulis dan gambar yang terkait, termasuk petunjuk dan penjelasan tentang cara menggunakan setiap fitur pada pemutar media VLC, terbaru, mudah dinavigasi, dapat dipahami, dan dapat diterjemahkan setidaknya dalam lima bahasa utama.

Mentor: Jean-Baptiste, Alex, Simon

ANALISIS

Jean-Baptiste dan saya telah berdiskusi tentang lingkungan baru tempat dokumentasi pengguna saat ini akan dimigrasikan untuk peningkatan dan dia membagikan dua link yang menunjukkan repositori Gitlab file sumber yang ditulis dengan Sphinx dan dokumentasi utama yang dihosting di Read the Docs. Dia mengatakan bahwa mereka berharap dokumentasi baru akan serupa dengan dokumentasi tersebut. Saya telah banyak meneliti tentang alat ini untuk mendapatkan pemahaman yang lebih baik tentang cara kerjanya.

Sphinx

Sphinx adalah solusi yang andal dan matang untuk dokumentasi software. Fitur ini mencakup sejumlah fitur yang diharapkan penulis, seperti publikasi sumber tunggal, penggunaan kembali konten melalui penyertaan, penyertaan bersyarat berdasarkan jenis konten dan tag, beberapa tema HTML yang matang yang memberikan pengalaman pengguna yang luar biasa di perangkat seluler dan desktop, referensi di seluruh halaman, dokumen, dan project Dukungan Indeks dan Glosarium serta dukungan internasionalisasi. ReStructuredText juga menggunakan reStructuredText sebagai bahasa markup-nya, dan banyak keunggulannya berasal dari keandalan dan kejelasan reStructuredText serta kemampuannya untuk menerjemahkan dokumentasi.

Baca Dokumentasi

Read the Docs menyederhanakan dokumentasi software dengan mengotomatiskan pembuatan, pembuatan versi, dan hosting dokumen untuk Anda. Dokumen ini tidak pernah tidak sinkron; yaitu, setiap kali Anda mengirim kode ke sistem kontrol versi favorit, baik itu Git, Mercurial, Bazaar, atau Subversion, Read the Docs akan otomatis mem-build dokumen sehingga kode dan dokumentasi Anda selalu yang terbaru. Read the Docs memiliki beberapa versi; Read the Docs dapat menghosting dan mem-build beberapa versi dokumen Anda sehingga memiliki dokumen versi 1.0 dan dokumen versi 2.0 semudah memiliki cabang atau tag terpisah di sistem kontrol versi Anda. Read the Docs bersifat gratis dan open source serta menghosting dokumentasi untuk hampir 100.000 project open source besar dan kecil dalam hampir semua bahasa manusia dan komputer.

VERDICT

Sphinx adalah alat yang sangat canggih dan Read the Docs dibuat di atasnya untuk menyediakan hosting dokumentasi Sphinx yang membuat dokumen Anda selalu terbaru di seluruh versi. Keduanya adalah serangkaian alat yang luar biasa yang dapat digunakan developer dan penulis teknis untuk membuat dokumentasi pengguna yang paling cocok bagi pengguna akhir.

Sphinx menyertakan dukungan untuk menerjemahkan dokumentasi ke dalam beberapa bahasa. Alat ini mendukung kontrol versi yang akan digunakan untuk mengelola dokumentasi. Tidak seperti wiki saat ini yang dapat diedit oleh siapa saja dan tidak menambahkan informasi yang tepat, sistem kontrol versi ini akan memastikan bahwa semua perubahan ditinjau terlebih dahulu sebelum digabungkan ke repositori utama. Kontrol versi juga akan membuat dokumentasi meningkatkan kontribusi open source ke project karena orang dapat membuat masalah, membuka permintaan pull, dll. Sphinx dan Read the Docs digunakan oleh daftar komunitas dan aplikasi hebat lainnya seperti; ASP.NET, Kernel, Julia, Jupyter, PHPMyAdmin, Write the Docs, dll. dan merupakan alat yang bagus untuk digunakan untuk dokumentasi pengguna VLC yang baru.

Saya tidak hanya membaca tentang alat-alat ini, saya juga membuat sampel dasar. Berikut adalah link-nya: https://gitlab.com/Didicodes/demo-vlc-user-documentation ke repositori Gitlab saya, sedangkan versi yang dihosting di readthedocs dapat ditemukan di sini: [https://vlc-user-documentation-demo.readthedocs.io/en/latest/](https://vlc-user-documentation-demo.readthedocs.io/en/latest/.

STRUKTUR DOKUMENTASI YANG DIUSULKAN

Saya membuat struktur untuk Dokumentasi Pengguna VLC yang dapat ditemukan di sini; https://docs.google.com/document/d/1Sy2V2IADoCyfnGBK70v8mkjiWK2tH-oWdUlDxAfQAYA/edit?usp=sharing. Sebelum penerapan struktur baru ini dimulai, struktur tersebut harus disetujui oleh mentor. Artinya, struktur tersebut kemungkinan akan berubah setelah ditinjau oleh mentor.

SASARAN PROYEK

  • Susun ulang dokumentasi.
  • Memperbarui dokumentasi agar sesuai dengan versi VLC modern.
  • Memigrasikan dokumentasi pengguna ke Gitlab menggunakan Sphinx dan ReadtheDocs.
  • Hapus gambar dan informasi yang tidak digunakan lagi.
  • Tulis ulang dokumentasi pengguna agar lebih mudah dipahami.
  • Siapkan untuk penerjemahan menggunakan Internasionalisasi Sphinx.
  • Buat dokumentasi yang didorong oleh komunitas sehingga pengguna dapat melaporkan atau menyelesaikan masalah apa pun yang dialami saat membaca dokumentasi.

MENGAPA PROJEK INI?

Saya selalu yakin bahwa menulis kode, memecahkan masalah, dan membuat software akan mencapai potensi penuhnya jika Anda juga memiliki kemampuan untuk mengedukasi orang lain tentang hal tersebut melalui tulisan. Secara pribadi, saya selalu tertarik dengan upaya yang dilakukan oleh komunitas VideoLAN dalam menciptakan solusi software gratis untuk multimedia. Sewaktu kecil, VLC media player selalu menjadi software yang saya gunakan saat mendengarkan musik atau menonton film karena suaranya sangat keras dan memiliki banyak fitur. Saya merasa terhormat dapat bekerja sama dengan komunitas yang telah membuat masa kecil saya menjadi luar biasa.

MENGAPA SAYA ORANG YANG TEPAT UNTUK PROJEK INI

Saya yakin saya adalah orang yang tepat untuk project ini karena:

  • Saya memiliki pengalaman sebelumnya dalam meningkatkan dokumentasi organisasi dan saya dapat menggunakan sistem kontrol versi apa pun, sehingga menjalankan perintah di Gitab tidak akan menjadi masalah. Selain itu, yang mendorong saya adalah mengerjakan proyek yang menciptakan nilai bagi banyak orang.
  • Saya percaya bahwa jika Anda ingin seseorang melakukan sesuatu dengan cara yang paling efisien, Anda harus mendokumentasikannya. Dengan mendokumentasikan proses Anda, Anda memastikan efisiensi, konsistensi, dan ketenangan pikiran bagi siapa pun yang terlibat.
  • Saya tahu kebutuhan pengguna VLC karena saya adalah salah satunya. Hal ini akan memungkinkan penulisan dokumentasi sedemikian rupa sehingga setiap pengguna lain di seluruh dunia dapat memahaminya pada pandangan pertama.