本頁面包含 Google 技術文件季度接受的技術寫作專案詳細資料。
專案摘要
- 開放原始碼組織:
- VideoLAN
- 技術撰稿人:
- Edidiong Anny Asikpo
- 專案名稱:
- 翻新 (重寫) VLC 使用者說明文件
- 專案長度:
- 標準長度 (3 個月)
Project description
ABSTRACT
「使用者」說明文件旨在協助使用者使用產品或服務,良好的使用者說明文件非常重要,因為它能讓使用者瞭解如何使用軟體、軟體功能、提示、技巧,以及解決使用軟體時遇到的常見問題。這也能降低支援成本,並成為產品的企業識別:良好的使用者說明文件是產品和開發團隊健康的象徵。
如果沒有良好的使用者說明文件,使用者可能不知道如何有效地執行上述操作。使用者說明書對於確保產品成功至關重要,因為良好的溝通是任何業務或產品的核心,而優質的說明書正是將這項溝通內容放入可管理的架構,讓所有人都能成功使用。
截至本文撰寫時,VLC 使用者說明文件的存取次數為 4,634,065 次,而 VLC 媒體播放器的下載次數每月約為 2,300 萬次 (從主要網站下載),這表示全球有許多人使用 VLC 媒體播放器,並可能想閱讀使用者說明文件,瞭解如何使用媒體播放器。不過,VLC 媒體播放器的使用者說明目前已過時且不完整 (上次修改日期為 2015 年 10 月 28 日),而 VideoLAN 社群希望透過這個專案改善使用者說明,讓使用者在使用 VLC 媒體播放器時,享有順暢的體驗。
目前狀態
目前,使用者說明文件可在 Wiki 頁面中找到。這項說明已過時、不完整、難以瀏覽或查找資訊,且未涵蓋媒體播放器目前版本的相關資訊,且只能翻譯成德文,這對不會閱讀英文的使用者來說是重大挫折。
為什麼我提出的使用者說明比目前的版本更優?
我們建議的使用者說明文件架構,可確保使用者享有效率、一致性和安心感。檔案包含書面指南及相關圖像,包括 VLC 媒體播放器各項功能的使用說明和說明,並支援至少五種主要語言,且是最新、容易瀏覽、易於理解且可翻譯的。
導師:Jean-Baptiste、Alex、Simon
分析
Jean-Baptiste 和我討論了新環境,我們會將目前的使用者說明文件遷移至該環境,以便進行改善。他分享了兩個連結,分別是使用 Sphinx 編寫的來源檔案 Gitlab 存放區,以及託管在 Read the Docs 的主要說明文件。他表示,他們希望新版說明文件與這兩個連結類似。我做了許多研究,進一步瞭解這些工具的運作方式。
人面獅身像
Sphinx 是功能強大且成熟的軟體文件解決方案。這項工具包含許多作者期待的功能,例如單一來源發布、透過包含項目重複使用內容、根據內容類型和標記設定條件式包含項目、多種成熟的 HTML 主題,可在行動裝置和電腦上提供絕佳的使用者體驗、跨頁面、文件和專案的參照、索引和詞彙表支援,以及國際化支援。它也使用 reStructuredText 做為標記語言,許多優點都源自 reStructuredText 的強大功能和簡單易懂的特性,以及其翻譯說明文件的能力。
Read the Docs
Read the Docs 可自動建構、版本管理及代管您的文件,簡化軟體文件作業。永遠不會同步,也就是說,當您將程式碼推送至慣用的版本管控系統 (無論是 Git、Mercurial、Bazar 或 Subversion) 時,Read「文件」都會自動建立文件,讓您的程式碼和說明文件隨時保持在最新狀態。它有許多版本;Read the Docs 可代管及建構多個版本的文件,因此只要在版本控制系統中建立不同的分支或標記,就能輕鬆取得 1.0 版和 2.0 版的文件。歡迎閱讀這份免費文件,並針對近 10 萬個大型和小型開放原始碼專案提供說明文件,而且幾乎適用於各種人類和電腦語言。
裁定
Sphinx 是一項非常強大的工具,而 Read the Docs 則是建構在 Sphinx 之上,為 Sphinx 文件提供代管服務,讓您的文件在各個版本中保持最新狀態。這兩項工具搭配使用,可讓開發人員和技術撰稿人為使用者製作最合適的使用者文件。
Sphinx 支援將說明文件翻譯成多種語言。它支援版本控制功能,可用於管理說明文件。與現有的 Wiki 不同,任何人都能編輯 Wiki 內容,但無法新增正確資訊。而這個版本控制系統會確保所有變更都會先經過審查,再合併至主要存放區。版本控制也會讓文件增加對專案的開放原始碼貢獻,因為使用者可以建立問題、提出合併要求等。Sphinx 和 Read the Docs 受到許多其他優秀社群的使用,例如 ASP.NET、Kernel、Julia、Jupyter、PHPMyAdmin、Write the Docs 等,也是用於新 VLC 使用者文件的絕佳工具。
我不只是瞭解這些工具,還建立了基本樣本以下是我的 Gitlab 存放區連結:https://gitlab.com/Didicodes/demo-vlc-user-documentation,而 readthedocs 上的託管版本可在以下連結找到:[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 國際化進行翻譯。
- 讓說明文件由社群驅動,讓使用者在閱讀說明文件時遇到任何問題,都能回報或解決。
為什麼要進行這個專案?
我一直相信,編寫程式碼、解決問題和建構軟體,如果能透過文字向他人說明,就能發揮最大潛力。我個人認為,VideoLAN 社群在打造多媒體軟體解決方案的免費解決方案時,總是相當著迷。從小到大,我聽音樂或看電影時,總是使用 VLC 媒體播放器,因為它音量很大,而且功能很多。能與這個讓我童年充滿歡樂的社群合作,我感到無比榮幸。
WHY AM I THE RIGHT PERSON FOR THIS PROJECT
我認為自己適合這個專案,因為:
- 我曾協助改善機構的說明文件,也能使用任何版本管控系統,因此在 Gitab 上執行指令不會有任何問題。此外,我希望自己努力打造的專案可以為使用者帶來價值。
- 我認為,如果您希望某人以最有效率的方式完成某項工作,您就會記錄下來。記錄程序可確保效率、一致性,並讓所有相關人員放心。
- 我知道 VLC 使用者的需求,因為我也是他們的一員。如此一來,全球所有使用者都能立即瞭解撰寫說明文件的方式。