本頁針對 Google 系列文件接受的技術撰寫專案提供詳細資料。
專案摘要
- 開放原始碼機構：
- 影片 LAN
- 技術文件撰寫者：
- Edidiong Anny Asikpo (Edidiong Anny Asikpo)
- 專案名稱：
- 翻新 (重寫) VLC 使用者說明文件
- 專案長度：
- 標準長度 (3 個月)
Project description
黑白
「使用者文件」旨在協助使用者使用產品或服務。完善的使用者說明文件非常重要，因為它可讓使用者有機會瞭解如何使用軟體、相關功能、提示和秘訣，以及解決使用軟體時的常見問題。並且可降低支援成本，並且組成產品的企業身分，優質的使用者文件代表產品 (開發團隊) 的健康狀態。
如果沒有優質使用者文件，使用者可能就無法有效率地完成上述事項。「使用者文件」在確保產品成功發揮關鍵作用，因為良好的溝通絕對是任何企業或產品的核心。妥善的文件則能確保溝通，並提供易於管理的架構，讓所有人都能存取所需資料。
截至本文撰寫時間為止，VLC 使用者文件的存取次數為 4,634,065 次，而 VLC 媒體播放器每個月約從主網站下載次數約 2,300 萬次。這表示世界各地有許多人都使用 VLC Media Player，如要瞭解如何使用媒體播放器，建議您閱讀這份使用者說明文件。然而，VLC 媒體播放器的使用者文件目前已過時且不完整 (上次修改時間為 2015 年 10 月 28 日)，而 VideoLAN 社群想利用這項專案改善使用者說明文件，讓使用者在使用 VLC 媒體播放器時享有流暢的體驗。
目前狀態
使用者文件目前會顯示在維基網頁上。比如過時、不完整、瀏覽或尋找資訊，並未涵蓋目前媒體播放器版本的資訊，而且只能以 Deutsch 進行翻譯，對閱讀英文的使用者來說是一大打折。
為何我的提議的使用者文件相較於現有文件有改善之處？
提議的使用者文件的結構主要在於提升，以確保使用者的效率、一致性，以及讓使用者高枕無憂。其中包含以至少五種主要語言撰寫的書面指南及相關圖片，包括說明和說明，說明如何使用 VLC 媒體播放器的每個功能，並提供符合現況、易於瀏覽、理解和翻譯的文字內容。
導師：尚班-洗體粉、亞歷山、西蒙
分析
Jean-Baptiste 和我談到的新環境將用於改善現有使用者文件，他分享了兩個連結，其中顯示了使用 Sphinx 編寫的來源檔案 Gitlab 存放區，以及「閱讀文件」上託管的主要說明文件，並表示他們希望新文件相似。我曾研究過這些工具，進一步瞭解這些工具的運作方式。
人面獅身像
Sphinx 是一套完善且成熟的軟體說明文件解決方案。它包括許多撰寫者期望的功能，例如單一來源發布、透過 include 重複使用內容；條件式包括根據內容類型和標記進行條件式；條件式則包括根據內容類型和標記，為行動裝置和電腦提供良好使用者體驗的多個成熟的 HTML 主題，也會參照網頁、文件和專案索引與詞彙表支援，以及國際化支援。此服務也使用 reStructuredText 做為標記語言，而且許多優點在於 reStructuredText 強大且直接了當，以及翻譯說明文件的功能。
閱讀說明文件
閱讀 Google 文件可自動建立文件、版本管理及代管文件，藉此簡化軟體說明文件。它不會不同步。也就是說，只要將程式碼推送至慣用的版本管控系統，無論是 Git、Mercurial、Bazaar 或 Subversion，《朗讀文件》都會自動建立文件，因此您的程式碼和說明文件永遠都能即時更新。它具有多個版本；閱讀 Google 文件可以代管及建立多種版本的文件，因此擁有 1.0 版的文件和 2.0 版的文件，就像在版本管控系統中個別建立一個分支或標記一樣簡單。閱讀「Google 文件」是免費的開放原始碼，而且代管了近 100,000 個大型與小型開放原始碼專案的說明文件，而且幾乎涵蓋所有人類與電腦語言。
驗證
Sphinx 是非常強大的工具，閱讀報告建構了 Sphinx 文件，持續更新不同版本的文件。開發人員和技術撰寫者可搭配使用這些實用的工具，建立最適合使用者的說明文件。
Sphinx 支援將說明文件翻譯成多種語言。可支援用於管理說明文件的版本管控。與目前的維基不同，任何人都可以編輯且不允許新增正確資訊，版本管控系統可確保所有變更在合併至主要存放區之前，都先經過審查。版本管控功能也會讓說明文件增加開放原始碼的貢獻，因為使用者可以建立問題、開放式提取要求等。Sphinx 閱讀 Google 文件時，會參考其他優秀和社群 (例如 ASP.NET、Kernel、Julia、Jupyter、PHPMyAdmin、Write the 文件等等) 使用文件。這項工具很適合用於新的 VLC 使用者說明文件。
我不是剛剛看了這些工具，還建立了基本樣本。這個連結：https://gitlab.com/Didicodes/demo-vlc-user-documentation 會導向我的 Gitlab 存放區，而閱讀文件的代管版本則列載於以下網址：[https://vlc-user-documentation-demo.readthedocs.io/en/latest/](https://vlc-user-documentation-demo.readthedocs.io/zh-TW/
提議文件的結構
我已為 VLC 使用者說明文件建立架構，列載於 https://docs.google.com/document/d/1Sy2V2IADoCyfnGBK70v8mkjiWK2tH-oWdUlDxAfQAYA/edit?usp=sharing。 這個新建築結構必須先經過導師的核准，才能開始導入。這表示導師可能會改變建築結構。
專案目標
- 重組說明文件。
- 請根據新版 VLC 更新說明文件。
- 使用 Sphinx 和 ReadtheDocs 將使用者說明文件遷移至 Gitlab。
- 移除過時的圖片和資訊。
- 改寫使用者說明文件，讓內容更容易理解。
- 設定使用 Sphinx Internationalization 進行翻譯。
- 依據說明文件社群的需求，讓使用者回報或解決閱讀說明文件時遇到的任何問題。
製作這項專案的好處
我一向認為編寫程式碼、解決問題及建構軟體可以充分發揮潛力，因為您同時能夠透過書面來授權他人。個人對於 VideoLAN 社群為打造多媒體軟體解決方案所付出的努力，我一向十分滿意。VLC 媒體播放器像兒童相信能與社群成員合作，為我帶來滿滿的童年提供支援。
我為什麼是這項專案的負責人
我認為自己是這項專案的負責人，原因如下：
- 我過去曾改善機構說明文件，而且可以使用任何版本管控系統，因此在 Gitab 上執行指令並不會造成問題。除此之外，促使我從事的專案為人帶來價值的專案。
- 我相信，如果您希望有人以最有效率的方式完成某件事，您需要提供相關資訊。只要記錄流程，就能確保所有參與人員的效率、一致性和高枕無憂。
- 我知道 VLC 使用者的需求，因為我是這類使用者。如此一來，世界各地的其他使用者都能一眼就瞭解文件內容。