本頁詳細說明 Google 文件季度接受的一項技術撰寫專案詳細資料。
專案摘要
- 開放原始碼組織：
- VideoLAN
- 技術撰稿人：
- Edidiong Anny Asikpo
- 專案名稱：
- 翻新 (重寫) VLC 使用者說明文件
- 專案長度：
- 標準長度 (3 個月)
Project description
草稿
「使用者」說明文件旨在協助使用者使用產品或服務。良好的使用者說明文件非常重要，因為前者可讓使用者學習如何使用軟體，以及軟體提供的功能、提示和秘訣，以及解決使用軟體時遇到的常見問題。同時也能降低支援成本，而且是產品企業形象的一環：一份良好的使用者記錄不僅是對開發團隊的產品健全度的跡象。
如果缺少完善的使用者文件，使用者可能不知道如何有效有效地執行上述操作。使用者文件可以發揮關鍵作用，確保產品成功，因為良好的溝通永遠是所有業務或產品的核心，而優質的文件則能讓通訊內容成為人人都能輕鬆使用的管理架構，讓所有人都能獲得成功。
在本文撰寫期間，VLC 使用者說明文件存取次數已達 4,634,065 次，而且每月從主要網站下載了約 2,300 萬次 VLC 媒體播放器，由此可見，全球許多人都使用 VLC Media Player，因此可能會想閱讀使用者說明文件，瞭解如何使用媒體播放器。然而，VLC 媒體播放器的使用者文件目前已經過時且不完整 (上次修改日期是 2015 年 10 月 28 日)，影片 LAN 社群希望利用這項專案來改善使用者文件，讓使用者在使用 VLC 媒體播放器時能有流暢的體驗。
目前狀態
目前使用者說明文件可在維基網頁上提供。「過時」、「不完整」、「無法瀏覽或尋找資訊」涵蓋媒體播放器目前版本的相關資訊，而且只能以德區文翻譯，對無法閱讀英文的使用者造成了重大阻礙。
為什麼我提供的使用者說明文件可進一步提升目前成果？
提案的使用者說明文件結構將可提高效率、一致性，並提供使用者高枕無憂。其中包含書面指南及相關圖片，包括如何使用 VLC 媒體播放器的各項功能的操作說明和說明，並提供至少五種主要語言的最新內容、易於瀏覽、易於瀏覽和翻譯。
導師：Jean-Baptiste、Alex、Simon
分析
Jean-Baptiste 和我談到新環境，說明目前的使用者文件將遷移至新的環境，以便改善服務。他分享了兩個連結，這些連結顯示使用 Sphinx 編寫的原始碼檔案的 Gitlab 存放區，以及「Read the 文件」代管的主要說明文件。他也表示我研究了許多關於這些工具的知識，想進一步瞭解這項工具的運作方式。
人面獅身像
Sphinx 是一套完善且成熟的軟體說明文件解決方案。其中包含許多撰寫者預期的功能，例如單一原始碼發布、透過 include 標記重複使用內容、條件式包括以內容類型和標記為依據的成熟 HTML 主題、多個適合在行動裝置和電腦上提供良好使用者體驗的成熟 HTML 主題，參照各個頁面、文件與專案索引與詞彙支援，以及國際化支援。以及使用 reStructuredText 做為標記語言，其中許多優點都來自 reStructuredText 的強大功能和明瞭性以及文件翻譯功能。
閱讀說明文件
請閱讀 Google 文件，透過自動建立、版本管理和代管文件的方式，簡化軟體說明文件。這項功能永遠不會不同步；也就是說，每當您將程式碼推送至慣用的版本管控系統時，無論是 Git、Mercurial、Bazaar 或 Subversion，Read 文件會自動建立您的文件，讓程式碼和說明文件隨時保持最新狀態。「Google 文件」可代管及建立多個版本的文件，因此，在 1.0 版和 2.0 版文件中保留文件，就像在版本管控系統中提供個別的分支版本或標記一樣簡單。「Google 文件」是免費的開放原始碼文件，幾乎支援將近 10 萬個大型和小型的開放原始碼專案，而且幾乎涵蓋人類和電腦語言。
裁定
Sphinx 是極為強大的工具，「閱讀文件」工具以頂端為基礎，提供 Sphinx 說明文件主機，讓您的文件在不同版本中保持最新狀態。開發人員和技術撰寫人員可以結合運用這些工具，建立最適合使用者的使用者說明文件。
Sphinx 支援將說明文件翻譯成多種語言。支援版本管控功能，以便用於管理說明文件。目前的維基模式是，所有使用者都能編輯，又不得新增正確的資訊，但這個版本管控系統會先審查所有變更，再與主要存放區合併。版本管控也將讓說明文件對專案更加開放原始碼，因為使用者可以產生問題、開放提取要求等。此外，許多其他優良社群和如 ASP.NET、Kernel、Julia、Jupyter、PHPMyAdmin、撰寫文件等社群清單都能使用 Sphinx 和讀取文件，而這種工具非常適合用於新版 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/en/latest/)。
提案文件結構
我建立了 VLC 使用者說明文件架構，可以在下列網址找到：https://docs.google.com/document/d/1Sy2V2IADoCyfnGBK70v8mkjiWK2tH-oWdUlDxAfQAYA/edit?usp=sharing。 在實作這種新結構之前，必須先獲得導師的核准。也就是說，在經過導師的審查後，這可能會改變住家結構。
專案目標
- 重組說明文件。
- 更新說明文件以符合新版 VLC。
- 使用 Sphinx 和 ReadtheDoc 將使用者說明文件遷移至 Gitlab。
- 移除過時的圖片和資訊。
- 重新撰寫使用者說明文件，讓內容更容易理解。
- 使用 Sphinx Internationalization 進行設定。
- 以說明文件社群為基礎，讓使用者可以回報或解決閱讀說明文件時遇到的問題。
為什麼是這項專案？
我一直有信心，只要能撰寫程式碼、解決問題和建構軟體，就能充分發揮其潛能，而我也能透過書面方式來啟發他人。我一直相當著迷，因為 VideoLAN 社群在建立適用於多媒體的免費軟體解決方案時，透過了努力不懈的努力。VLC 媒體播放器在成長過程中一直都是我聆聽音樂或看電影時使用的軟體，因為其音量非常大，而且具備眾多功能。我們很榮幸能與社群攜手合作，一起為我的童年增添趣味。
我為何是這項專案的負責人
我相信自己是本專案的負責人，原因如下：
- 我過去在改善組織文件方面有經驗，可以使用任何版本管控系統，因此在 Gitab 上執行指令應該不會造成問題。此外，我主導的是，推動的是能為使用者創造價值的專案。
- 我認為要讓他人以最有效率的方式採取行動，你會記錄下去。透過記錄流程，可以確保所有參與人員的作業效率、一致性和高枕無憂。
- 我知道 VLC 使用者的需求。如此一來，全球其他使用者都能快速理解此文件。