本頁將詳細說明 Google Season of Docs 接受的技術文件寫作專案。
專案摘要
- 開放原始碼組織：
- VLC
- 技術撰稿人：
- Abhishek Pratap Singh
- 專案名稱：
- 繼續「翻新 VLC 使用者說明文件」
- 專案長度：
- 標準長度 (3 個月)
Project description
文件目前狀態
VLC 使用者說明文件正在進行現代化和更新。目前正在進行轉換，從以維基為基礎的舊版說明文件 [1]，轉變成由 ReadTheDoc 代管的 sphinx 現代化使用者說明文件 [2]。
TARGET AUDIENCE
除了一般媒體播放器，目標對像也是好奇且想探索 VLC 媒體播放器的好奇心，且就某種程度上來說，這個平台能為開發人員提供簡易的參考指南。因此，我打算同時提供以 GUI 為基礎的指示 (以及相關圖片) 和以 CLI 為基礎的方法 (以及程式碼片段)，讓使用者可以自由選擇。
我認為說明文件中的用語 (尤其是「統一發票」一節) 應適度降低，讓公認電腦操作人員能夠瞭解並實作本指南。另一方面，也不應該讓編碼器失去興趣，或是說明太冗長 (尤其是 CLI 部分)。
您可以在頁面開頭提及先決條件，或是保留可供熟悉的使用者略過的選用部分，以便取得平衡。
如要建立翻譯內容，目標對象是 VLC 的開發人員/使用者，他們必須熟悉英文和要翻譯的語言。
工具
新的說明文件是由 Sphinx 建構，並託管於 ReadTheDocs，而版本管控系統則是在 GitLab 中實作。我曾使用過 Git 和 GitHub，因此能很快上手 GitLab，但仍有部分不同功能需要花點時間學習。
至於 Sphinx，我曾讀到一位開源愛好者提到，許多機構都使用 Sphinx 製作說明文件 (其中最著名的例子是 Blender，該公司使用 Sphinx 製作使用手冊 [3] 和 API 說明文件 [4])。
我對 ReadTheDocs 稍有認識，這是個不錯的工具，可用於版本控制和代管技術文件。因此，我可以毫無問題地建構 VLC 說明文件，而且我熟悉所使用的格式化方式：reStructured Text。
在翻譯方面，VLC 會使用 Babel 產生 .po 檔案，以便實作 i18n 和 l10n。目前，我正在熟悉 Babel 工作流程，以及如何使用 Sphinx 建構 .mo 檔案。
我打算利用這段時間，進一步熟悉上述工具的複雜性。
可交付項目和每週時程
在 2019 年專案中，我們已涵蓋安裝、介面、音訊、影片、播放等部分 (大部分的基本功能)。因此，針對 2020 年專案，我想更新並處理使用者文件的進階用途部分。
交付 1 [第 1-2 週]：更新轉碼說明文件，如 #7[5] 中所述。
- 轉碼
- 轉碼多部影片
- 新增標誌
- 合併影片
- 擷取音訊及擷取檔案音訊
- 擷取 DVD
成果 2 [第 3-4 週]：更新使用 VLC 做為網路外掛程式 [6]，並在 Firefox 77、Chrome 83 和 Edge 83 中進行測試。
- 使用影片建立網頁
- 嵌入標記屬性
- JavaScript API 說明
成果 3 [第 5 週]：測試指令列介面 [7] 指令並進行相應更新。
- 串流
- 模組選項
- 項目專屬選項
- 篩選器
第 6 週：上述三項成果的緩衝週。
成果 4 [第 7-8 週]：準備翻譯。 除了更新外，我也會準備翻譯成其他語言。這一點很重要，因為在翻譯完成後，沒有英文背景的使用者就能閱讀說明文件 (順帶一提，VLC 也因此更接近達成全球統治 [8]的目標)。
如提案的「工具」一節所述，VLC 目前使用 Babel 產生 .po 檔案，用於翻譯。我會記錄使用者/志工的程序：
- 在本機下載並建構基本文件。
- 使用 Babel 產生必要檔案。
- 輸入字串的翻譯。
- 使用 Sphinx 建構已翻譯的文件。
- 提交變更。
成果 5 [第 9-10 週]：準備模組說明文件。如同導師先前討論的，我規劃分為兩部分製作單元文件。
第 1 部分：透過指令碼建立靠近模組的檔案，該指令碼會從程式碼庫中尋找有效的選項，並從對應的 Wiki 頁面中擷取一行用法 (以及預設值)。這會是基本草稿。
第 II 部分：建構特定平台結構，連結特定平台 (Windows，如果時間允許，也連結 Fedora) 的所有模組、外掛程式和選項。
建立靠近模組的檔案，可確保說明文件與原始碼相近。採用由下而上的做法時，主要模組說明文件會是結合第 1 部分的檔案，以及第 2 部分建立的結構做為參考。
透過自動化作業建立的檔案需經過審查，但首要任務是製定功能架構。完成後，我會根據可用時間審查檔案，驗證選項。架構已列為優先項目，因為開發人員和維護人員可在架構推出後，開始新增相關用途。
獎勵成果 [第 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/zh-TW/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