本頁針對 Google 系列文件接受的技術撰寫專案提供詳細資料。
專案摘要
- 開放原始碼機構：
- VLC
- 技術文件撰寫者：
- Abhishek Pratap Singh
- 專案名稱：
- 繼續翻新 VLC 使用者說明文件
- 專案長度：
- 標準長度 (3 個月)
Project description
說明文件目前的狀態
VLC 使用者說明文件正在翻新並更新中。轉換作業仍在從以維基為基礎的舊版說明文件 [1] 轉換為由 ReadTheDocs 代管的新型使用者說明文件 [2]。
目標對象
目標對像是充滿好奇的使用者，並想探索 VLC 媒體播放器以外的一般媒體播放器功能，在某個程度上，目標對像也可以給予開發人員簡單參考指南，對他們有所幫助。因此，我打算同時提供 GUI 式指令 (及相關圖片) 和以 CLI 為基礎的方法 (連同程式碼片段)，讓使用者能自由選擇。
我認為說明文件 (尤其是「統一發票」部分) 的用語應足以理解並實作指南。另一方面，不應太冗長或令人難以理解 (尤其是 CLI 部分)。
如要達到最佳平衡，可以在頁面開頭提及必要條件，或是保留方便瀏覽的選填部分。
在建構翻譯方面，目標對像是 VLC 的開發人員/使用者，對於英文的瞭解和要翻譯成什麼語言。
工具
新版文件是由 Sphinx 建構而成，並由 ReadTheDoc 代管，而版本管控系統則在 GitLab 中實作。我曾使用 Git 和 GitHub 並瀏覽過 GitLab 相關經驗，但某些功能需要一段時間學習，但我還是花了一些時間學習。
就 Sphinx 而言，我曾有一位開放原始碼愛好者評論機構使用這項工具建立文件 (其中以 Blender 為例，它使用 Sphinx 建構使用者手冊 [3] 和 API 說明文件 [4])，表示我曾瞭解這一點。
我稍微熟悉了 ReadTheDocs，這是適合用於版本管理和代管技術文件的好工具。因此，我能夠輕鬆製作 VLC 文件，而且很熟悉使用的重編文字格式。
為進行翻譯，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 週：為上述 3 項交付項目準備緩衝週。
交付 4 [7-8 週]：準備翻譯。 除了更新服務外，我也將準備翻譯成其他語言。這一點與翻譯完成後一樣重要，沒有英文背景的使用者都可以閱讀說明文件 (附帶注意事項，以 VLC 為例，僅將有助於達成世界名次目標 [8])。
如提案的「工具」部分所述，VLC 目前使用 Babel 產生 .po 檔案進行翻譯。我會記錄使用者/志工的程序：
- 在本機下載及建構基礎說明文件。
- 使用 Babel 產生必要檔案。
- 輸入字串的翻譯。
- 使用 Sphinx 建構翻譯後的說明文件。
- 提交變更。
交付項目 5 [第 9 至 10 週]：準備模組說明文件。如同之前的導師課程，我打算將兩個單元的說明文件準備成單元文件。
第 1 部分：透過指令碼建立靠近模組的檔案，該指令碼會從程式碼集中尋找有效選項，並從對應的維基網頁擷取這些選項的單行用法 (和預設值)。這會做為基本草稿。
第 - II 部分：建構平台專屬結構，連結特定平台的所有模組+外掛程式+選項 (適用於 Windows 以及 Fedora 的適用時間)。
在模組附近建立檔案可確保說明文件接近原始碼。使用「由下而上」的方法，主要單元說明文件將透過合併第 - I 部分製作的檔案，並使用第 - II 部分建立的結構做為參考。
透過自動化功能建立的檔案必須接受審查，但第一個首要任務是建立功能架構。完成後，我會檢查檔案確認選項。因此，在架構可供使用時，開發人員和維護者也可以開始優先執行架構，也可以開始新增相關用途。
提供獎勵 [第 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