本頁針對 Google 系列文件接受的技術撰寫專案提供詳細資料。
專案摘要
- 開放原始碼機構：
- VLC
- 技術文件撰寫者：
- Avii
- 專案名稱：
- 建立單一行動通訊埠的 VLC 使用者說明文件 (Android)
- 專案長度：
- 標準長度 (3 個月)
Project description
黑白
使用者說明文件可做為靜態支援系統，用來協助使用者。當中同時提供產品或服務的技術與非技術資訊。可協助使用者瞭解如何使用軟體或服務。畢竟，有些人可能想聯絡支援團隊，或是等候電子郵件回覆 (如果對方能做出一些小方向回應、訣竅或技巧)，使用者說明文件就能派上用場。這也有助於降低支援成本，且公開產品及開發人員團隊的身分。
光是在 Google Play 商店，Android 版 VLC 的下載次數已突破 1 億次。VLC 為行動通訊埠提供許多功能，從影音播放到網路串流都有。使用者通常想使用超棒的功能，但是他們無法這麼做。搜尋網誌或隨機影片需要很長的時間與耐心等待，但資訊的真實性。目前 VLC 會在維基網頁上代管 Android 使用者說明文件的 VLC，但這些功能的部分說明較少，甚至完全沒有。此外，維基網頁上次更新於 2019 年 3 月。目前的專案將提供具備新設計且易於使用 Android 通訊埠的使用者說明文件。
目前感受
維基網頁已經過時，其中所含的最新版 VLC 的資訊較少。而且不易瀏覽。文件閱讀語言不只有英文。該屬性完全不含功能說明。
分析
-> 目前的說明文件已過時，需要以全新方式編寫，並使用其他平台和工具。
-> 大部分的 Android 使用者不太具備技術知識，或完全不需要相關技術知識。但有些人需要更多功能的技術資訊。最好針對上述各項目的撰寫及維護兩份不同的文件，或者，您也可以在同一份說明文件中，根據技術性和非技術性來區分功能，因而造成混淆。同樣地，大部分使用者都習慣觀看自己看到的 UI 或使用的功能，因此很難做出判斷，判斷某件事是否屬於技術性或非技術性。所以我們要簡化他們
-> 大多數使用者會嘗試透過智慧型手機取得資訊，其餘使用者則嘗試透過電腦或其他裝置取得資訊。因此說明文件必須能輕鬆根據各種螢幕大小調整。也不會對瀏覽造成混淆。
-> Android 連接埠並非提供電腦版的所有功能，而且在兩個連接埠上也不同。這是因為電腦版應用程式的開發時間較長，而且已達到飽和狀態，相較之下，行動連接埠相對較新，仍在開發中。除此之外，雖然現今的行動裝置功能越來越強大，但我們在多數情況下可以配合使用者需求來加入功能類型也很明顯。開放任何功能就是浪費開發資源。因此，我們不建議您只根據功能說明兩份說明文件，
以上述數據分析為基礎1. 截至目前，電腦版使用者說明文件已開始使用 Sphinx 說明文件產生器，並閱讀 Google 文件的主題。針對 Android 通訊埠使用相同的方法，可以協助我們： -> 輕鬆合併兩項說明文件。 -> 針對各種螢幕大小進行最佳化。 -> 透過 Google 桌面說明文件瀏覽至 Android 使用者說明文件時，可享有流暢的使用體驗
- 根據章節、章節和子章節在應用程式中的相對位置來分隔各個章節。例如，背景/PiP 模式位於「更多」->「設定」->「影片」內，因此章節結構會
- 更多
- |__設定
- | |__媒體資料庫
- | |__影片 -->背景/PiP 模式
- ： -> 這個做法可讓使用者輕鬆前往需要幫助的特定位置，只要比較在應用程式中的相對位置即可，因此更容易存取。針對每項功能，我們進一步區分技術與非技術部分。我們首先必須寫出非技術性的說明，然後在下方進一步標明或標示同一功能的技術部分 (如有)。這可能會導致部分重複，但可確保非技術性多數的多數使用者都能享有流暢的使用體驗。這麼做也可以提高可維護性，為日後帶來助益。由於應用程式達到飽和度狀態，相對 UI 不會大幅變更，因此未來如果新增/移除新功能，我們只需重構該區段。如果整個使用者介面有所變更，我們都可以重新排列文件的區段/章節，或是重新建構整個文件。因為螢幕截圖必須取代目前的使用者介面，所以我們都需要修改整份文件。實際示範請見：https://avinal.gitlab.io/vlc-android-docs/
說明文件的每一個部分都應包含 清楚標示 的螢幕截圖 、功能說明，以及功能的相關提示與秘訣 (若有的話)。
-> 從電腦獨立開發這份使用者說明文件，有助於我們只需幾個步驟，就能合併兩種說明文件，而不影響目前的說明文件，也不影響到在開發期間受到此影響。建議您在開發完成後，將整份說明文件加入電腦版說明文件的 Android 部分，並為 Android 說明文件建立 VLC 的永久連結。
-> 更多改善項目包括重新設計電腦版使用者說明文件的起始網頁，讓使用者直接選擇自己偏好的作業系統，然後重新導向至所選作業系統的說明文件。由於 Windows、MacOS 和 Linux VLC 使用者說明文件的設計經過精心設計，且已經過探討，我們可能會提供 Windows/MacOS/Linux、Android 或 iOS 的選項。如此一來，就能清楚區隔使用者的文件，只提供一個連結，可用於所有通訊埠。
為什麼提供我推薦的使用者文件？ 這份建議的使用者說明文件架構為根據使用者尋求協助的常見模式，提供使用者協助。這份說明文件涵蓋了簡潔、清楚明瞭、外觀和風格、技術知識等所有必要功能，盡可能讓簡單易用且使用者體驗更臻完善。此架構也能輕鬆維護，因為不再需要維護每個通訊埠的個別使用者說明文件。
我為何要擔任這項專案的負責人？ -> 我撰寫程式碼已有 2 年，經常需要打開某些程式庫或某些軟體的 API 說明文件，甚至記錄自己的程式碼。因此我清楚瞭解大家想透過說明文件看到什麼內容、他們面臨的問題，以及他們如何取得協助。我能運用相同的經驗，撰寫一致且易於閱讀的文件。
-> 我一直在 Quora、Stack Overflow 和其他平台上撰寫技術內容。我知道講解內容的方式相當有吸引力，而且讓人容易理解。
-> Android 版 VLC 是功能強大且廣為人知的工具，但其多數功能不明，也未提供相關說明。多年來，我一直在電腦和行動平台上使用 VLC，我也知道使用者可能會遇到哪些問題。我深深耕耘我所學的知識與經驗，保證提供優質的文件。