本頁面包含 Google 技術文件季度接受的技術寫作專案詳細資料。
專案摘要
- 開放原始碼組織：
- VLC
- 技術撰稿人：
- Avii
- 專案名稱：
- 為一個行動端移植版本 (Android) 建立 VLC 使用者說明文件
- 專案長度：
- 標準長度 (3 個月)
Project description
ABSTRACT
使用者說明文件可做為靜態支援系統，協助使用者。提供產品或服務的技術和非技術資訊。可協助使用者學習如何使用軟體或服務。並非所有使用者都想聯絡支援團隊，或是等待電子郵件回覆，如果他們只需要一點指引、訣竅或技巧，正透過使用者說明文件做到這點也能降低支援成本，且是產品的健康度和開發團隊的識別身分。
僅從 Google Play 商店，就下載了超過 10 億次的 Android 版 VLC。VLC 為其行動連接埠提供許多功能，包括播放音訊到網路串流等。許多人想要使用這些很棒的功能，但卻無法順利操作。搜尋相關網誌或隨機影片需要花費大量時間和耐心，而且所獲得的資訊仍無法保證真實性。目前，VLC 在 wiki 頁面上提供 VLC for Android 使用者說明文件，但對這些功能的說明不多，甚至沒有。此外，Wiki 頁面上次更新時間為 2019 年 3 月。目前的專案將提供新的使用者說明文件，採用現代化設計，並讓 Android 移植作業更容易上手。
目前情況
維基百科頁面完全過時，且只包含少量最新版 VLC 的相關資訊。此外，這些網站也不易瀏覽。目前沒有可供選擇的選項，無法以英文以外的語言閱讀說明文件。此平台完全不含功能說明。
分析
-> 目前的說明文件已過時，需要以新方式撰寫，並使用不同的平台和工具。
-> 大部分 Android 使用者幾乎沒有技術知識。但有些人需要更多關於功能的技術資訊。為上述每個目的編寫及維護兩份不同的文件並不理想。或者，即使在同一份說明文件中，以技術和非技術區分功能也會造成混淆。由於大多數使用者都會習慣他們看到的 UI 或使用的功能，因此每個人難以判斷問題是否屬於技術或非技術性質。因此，我們希望為他們簡化這項作業。
-> 大多數使用者會透過智慧型手機取得資訊，其餘則透過電腦或其他裝置取得。因此，說明文件應能輕鬆調整為任何螢幕大小。也不會混淆瀏覽
-> 並非所有電腦版功能都適用於 Android 版，而且即使適用，在兩個版本中運作的方式也不盡相同。這是因為電腦版應用程式已開發一段很長的時間，並已達到飽和狀態，相較之下，行動版應用程式則是相對較新，仍在開發中。除此之外，雖然行動裝置的功能越來越強大，但我們可納入的功能類型仍有明顯限制，這主要是因為使用者的需求。提供無人使用的功能，只會浪費開發資源。因此，不建議同時根據功能對兩份說明文件進行對話。
根據上述分析，我建議採取以下做法。1. 電腦版使用者說明文件目前使用 Sphinx 說明文件產生器和「閱讀文件」主題。使用相同的文件格式為 Android 端口帶來以下好處： -> 可輕鬆合併兩份文件。 -> 這種網站能在所有螢幕大小上呈現最佳效果。 -> 透過電腦版說明文件前往 Android 使用者說明文件時，享有流暢的使用體驗
- 根據章節、章節和子章節在應用程式中的相對位置進行分隔。舉例來說，背景/PiP 模式位於「更多」->「設定」->「影片」中，因此章節結構會是
- 更多
- |__設定
- | |__媒體庫
- | |__Video -->Background/PiP Mode
- ： -> 這種做法可讓存取更加便利，因為使用者只要將應用程式與應用程式中的相對位置進行比較，就能輕鬆前往需要協助的部分。針對每項功能，我們可以進一步區分技術和非技術部分。我們會先撰寫非技術性的簡易說明，然後在下方進一步標示同項功能的技術部分 (如有)。這可能會導致重複，但可確保非技術人員順利使用。這也有助於日後的維護工作，由於應用程式會達到飽和狀態，相對的使用者介面不太可能有太大變化，因此如果日後新增/移除新功能，我們只需重構該部分即可。如果整個 UI 都變更，我們可以重新排列各節/章節，或重新建構整個文件，在任何情況下，我們都需要修改整個文件，因為螢幕截圖必須替換，才能與目前的 UI 相符。如需實際操作示範，請前往：https://avinal.gitlab.io/vlc-android-docs/
說明文件的各節都包含標示的螢幕擷取畫面 、功能說明、與功能相關的提示與訣竅 (如果有的話)。
-> 從電腦獨立開發這份使用者說明文件，有助於我們在幾個步驟內合併兩份說明文件，且不會影響目前的說明文件，也不會在開發期間受到其影響。建議您在開發完成後將整份說明文件放在桌面說明文件的 Android 部分，然後為 Android 說明文件的 VLC 建立永久連結。
-> 其他改善項目可能包括重新設計電腦版使用者說明文件的首頁，讓使用者直接選擇偏好的作業系統，然後重新導向至所選作業系統的說明文件。由於 Windows、macOS 和 Linux 的 VLC 使用者說明文件已設計完畢並翻譯完成，因此我們可能會提供 Windows/macOS/Linux 或 Android/iOS 的選項。這麼做可讓使用者文件分開且統一，只需一個連結即可用於所有端口。
為什麼我提出的使用者說明較佳？我們建議的使用者說明文件架構，是根據使用者尋求協助時常見的模式而定。說明文件結合了所有必要的功能 (例如簡單、清楚、外觀和技術知識)，盡可能提升使用便利性和使用者體驗。這些 API 也易於維護，因為不再需要逐一維護每個連接埠的使用者文件。
WHY AM I RIGHT PERSON FOR THIS PROJECT? -> 我已經編寫程式碼 2 年了，經常需要查看特定程式庫或某些軟體的 API 說明文件，甚至是記錄自己的程式碼。我確切知道大家期望在說明文件中看到的內容、他們遇到什麼問題，以及他們如何取得協助。我可以將相同的經驗運用於撰寫一致且易於閱讀的說明文件。
-> 我一直在撰寫 Quora、Stack Overflow 和其他多個平台的技術內容。我知道該如何以吸引人且容易理解的方式解釋內容。
-> Android 版 VLC 是一款功能強大且廣為人知的工具，但大部分功能都未知或沒有相關說明。我已經在電腦和行動平台上使用 VLC 多年，因此知道使用者可能會遇到哪些問題。我會運用所有知識和經驗，確保提供優質的說明文件。