本頁面包含 Google 技術文件季度接受的技術寫作專案詳細資料。
專案摘要
- 開放原始碼組織：
- 創用 CC
- 技術撰稿人：
- nimishnb
- 專案名稱：
- 詞彙使用指南
- 專案長度：
- 標準長度 (3 個月)
Project description
專案摘要
Vocabulary 有極大潛力，可用於建構網站的主要 UI 元件程式庫。它需要的是完善且適合一般使用者的操作說明指南。開發人員的重要資訊 (例如元件指南、使用規格和設定調整) 是任何說明文件的重要內容。這不僅能讓現有使用者瞭解詞彙持續增加並達到新里程碑，還能促進詞彙在較新專案中的使用率。我擔任實習生的期望成果，不僅是撰寫實用指南，說明如何使用現有的元件，還包括設計及開發 Vocabulary、Vue-Vocabulary 和 Fonts 的首頁 (並為每個首頁建立整合說明文件)。
專案計畫
問題：文件是決定某個開放原始碼程式庫成敗的其中一個主要原因。開發人員在選擇建構應用程式所需的適當技術堆疊時，會思考的主要問題是：「程式庫是否有完善的說明文件？是否維護良好？是否有可觀的使用量和錯誤支援？」這些正是我們在進行這個專案構想時，應該問自己的問題。從軟體工程的角度來看：
需求分析：我們迫切需要一份簡潔且完整的說明文件，以滿足我們的需求。缺乏文件會影響開放原始碼應用程式的未來前景，而且是不可忽視的重要因素。提供這些說明文件的連結，應為有吸引力的首頁，立即瞭解使用者的興趣。文件應經過妥善安排，以便順利進行流程。
規格：可根據需求決定規格。說明文件內容可依據 CC Netlify 網站上顯示的資料，以及 semantic-ui、scikit-learn、numpy、Bootstrap 等知名說明文件的靈感來源。這項工作的輸出內容將是到達網頁和完整說明文件指南。
目前與 Vocabulary、Vue-Vocabulary 和 Fonts 相關的常見問題：
文中並不存在，即使其中有部分內容是散佈在各網站中。這不會讓使用者、開發人員或外部貢獻者無法使用我們的程式庫。
您必須額外點選幾下，才能前往特定元件並複製對應的程式碼。簡單的 Google 搜尋，例如「分頁元件 CC 字彙」不會傳回所需資訊。說明文件指南中的「搜尋」選項能夠大幅改善使用者體驗。
針對元件提供更詳細的文字說明，說明不明顯的細節。
沒有即時執行選項。JSFiddle 等多個網站都支援即時執行功能，開發人員不必執行整個應用程式，就能體驗元件的運作方式。
解決方法
您可以採用多種解決方案。不過，我會在這裡簡單提及幾個，並在結論部分提供最終解決方案：
= 使用 readthedocs readthedocs 是撰寫開放原始碼程式庫說明文件的知名解決方案。這個工具以 Python 說明文件工具 Sphinx 為基礎。
優點：
- 廣泛接受的文件產生形式，由以太坊 (Solidity) 等機構使用。
- 最佳化結構化的說明文件。
- 免費提供靜態代管服務。
缺點：
- 沒有絕對的樣式控制。
= 使用 Sphinx 我們也可以在說明文件中使用 Sphinx，它提供多種功能，可滿足我們所有的需求。
優點：
- 最常用於說明文件的 Python 工具。
- 也支援說明文件搜尋功能。
- 您可以使用自訂 CSS 覆寫預設 CSS，並透過 .rst 檔案控制 HTML。
缺點：
- 包括使用 Python 編寫程式碼，以及重組文字格式 (.rst)，而這類格式與建議的專案語言不同。
= 使用 Jekyll 佈景主題 Jekyll 佈景主題已整合至 GitHub 頁面，且有現有範本可供您視需求自訂。
優點：
- 可用於各種用途的現成說明文件主題。
- 預設的 CSS 和樣式可能會以自訂樣式覆寫，同時控管 HTML。
- 提取預設的 Primer CSS 來建構網頁。
- 與 GitHub 頁面輕鬆整合。
缺點：
- 可能無法提供最佳的文件結構。
=使用 GitHub 頁面 標準 GitHub 頁面可用於建構靜態網站 (HTML、CSS、JS)。
優點：
- 無論問題為何，您都能完全掌控。
- 可彈性決定版面配置、顏色和樣式。
- 輕鬆使用 Vocabulary 元件。
- 輕鬆嵌入程式碼片段和即時執行連結。
缺點：
- 這可能會比較費時。
= 使用 Haroopad 這會提供其他 Markdown 解決方案。
優點：
- 只需編寫少量繁瑣的程式碼。
- 請專注於編寫完美的說明文件。
缺點：
- 無法控管 CSS。
- 可能不具備最佳社群支援服務。
- 可能不支援 MDX。
= 使用 MKDocs 這會提供另一個 Markdown 替代解決方案。
優點：
- 這會涉及最少的繁瑣程式碼 (再次)。
- 編寫更多，程式碼更少的方法。
缺點：
- 無法控管 CSS。
- 可能無法擁有最佳的社群支援。
- 使用 Python；可能需要進一步啟動 Amazon S3 執行個體。
= 使用 VueJS +StorybookJS 這個方法經常用於詞彙及其存放庫。
優點：
- 根據過往工作經驗，堅持使用保證可正常運作的技術。
- 熟悉程式碼集。
- 這個領域沒有可靠的技術。
缺點：
- 同樣目的的簡易選項也可能會出現。
總而言之，我對 VueJS+Storybook 方法 (HTML、CSS、JS) 也很熟悉，因此想找出最適合採用的做法。不過，這也意味著我們不會在開發這個應用程式時完全不考慮安全性。使用 CC-Vocabulary 元件也相當簡單。不過，決定說明文件結構時，請務必考量閱讀說明文件中，內容按子標題的方式。Semantic-UI 網站 (使用 StoryBook) 讓我留下深刻印象，因為它採用極簡風格，只要點按幾下，使用者就能輕鬆找到所需內容。除了 Semantic-UI 之外，我還參考了 Material Design、Primer、Bootstrap 和 Carbon Design 等，以便將其用於我的 UI 樣式指南和設計系統。我們也可以查看現成的 Jekyll 說明文件主題，從中汲取靈感。