本頁針對 Google 系列文件接受的技術撰寫專案提供詳細資料。
專案摘要
- 開放原始碼機構：
- 創用 CC
- 技術文件撰寫者：
- nimishnb
- 專案名稱：
- 詞彙使用指南
- 專案長度：
- 標準長度 (3 個月)
Project description
專案簡介
字彙非常有潛力，可做為建立網站的主要使用者介面元件程式庫。必備功能是一位淺顯易懂的說明指南。元件指南、使用規格和設定調整等重要開發人員資訊，都是說明文件中不可或缺的一部分。這麼做不僅能鼓勵現有使用者瞭解詞彙量如何持續擴張並達成新的里程碑，還能在較新的專案中提升使用「詞彙」。我將實習結果當成實習生實現的理想結果，不僅要寫出使用現有元件的簡單指南，還針對「詞彙」、「Vue-Vocabulary」和「字型」設計及開發首頁 (連結至每種工具的整合說明文件)。
專案計畫
問題：說明文件是判斷特定開放原始碼程式庫成效的主要原因之一。在選擇合適的技術堆疊來建構應用程式時，開發人員最關心的是「資料庫是否已妥善記錄？資源維護情況是否妥善？其中是否有大量的使用和錯誤支援服務？」。在討論專案構想時，我們應該自行思考以下哪些問題。從軟體工程的角度來看：
需求分析：我們迫切需要提供精簡且經過整合的說明文件，以滿足我們的需求。缺乏說明文件會影響開放原始碼應用程式的未來觀點，也是不可或缺且不可忽略的元件。因此，建議前往充滿吸引力的首頁，立即吸引使用者的注意。說明文件內容必須妥善規劃，有助於流暢地完成整個流程。
規格：視需求而定，可以根據需求決定規格。說明文件內容取自 CC Netlify 網站上的資料，並參考語意 UI、scikit-learn、numpy、Bootstrap 等知名說明文件的靈感。這項工作輸出內容會是必要的到達網頁，以及完整的說明文件指南。
「詞彙」、「Vue-Vocabulary」和「Fonts」目前有一些一般問題：
我們缺少說明文件，即使其中有部分文件，仍遍布整個網路。此舉不會讓使用者、開發人員或外部協作者使用我們的程式庫。
如要取得特定元件並複製其對應的程式碼，請點按額外操作。以「分頁元件 CC 詞彙」這類簡單的 Google 搜尋作業，並不會傳回所需資訊。說明文件指南中的「搜尋」選項可大幅提升使用者體驗。
撰寫較不明顯的元件說明，用文字提供較詳細的說明。
沒有已上線的選項。許多網站都支援即時執行作業，例如 JSFiddle，因此開發人員不必執行整個應用程式就能瞭解元件的視覺效果。
解決方法
有多種可能的解決方案。不過，我將跟您分享幾件事，最後展示我最終的解決方案：-
= 使用 readthedocs readthedocs 是撰寫開放原始碼程式庫說明文件的知名解決方案。一切是以 Python 說明文件工具 Sphinx 為基礎。
優點：
- 廣泛接受的文件產生形式，像以太坊 (Solidity) 等機構使用。
- 最佳結構化說明文件。
- 免費靜態託管。
缺點：
- 沒有絕對的樣式控制項。
= 使用 Sphinx 我們本身可以在說明文件部分使用 sphinx，因為其功能滿足我們的所有目的。
優點：
- 最常用於說明文件的 Python 工具。
- 也支援說明文件搜尋功能。
- 您可以使用自訂 CSS 覆寫預設 CSS；部分 CSS 可透過 .rst 檔案控管。
缺點：
- 這可能涉及以 Python 編寫程式碼，以及重結構化文字格式 (.rst)，這會與建議專案語言有不同之處。
= 使用 Jekyll 主題
優點：
- 各種用途的文件主題皆可立即使用。
- 您還可以使用自訂樣式覆寫預設的 CSS 和樣式，同時控制 HTML。
- 提取預設的 Primer CSS 來建立網頁。
- 輕鬆與 GitHub 頁面整合。
缺點：
- 可能無法提供最完善的文件架構。
=使用 GitHub 頁面 建立靜態網站 (HTML、CSS、JS) 的標準 GitHub 頁面。
優點：
- 幾乎可完全掌控所有問題。
- 擁有最大的彈性，決定版面配置、顏色和樣式。
- 輕鬆使用詞彙元件。
- 輕鬆嵌入程式碼片段及即時執行連結。
缺點：
- 可能較為耗時。
= 使用 Haroopad 這可以提供另一種 Markdown 解決方案。
優點：
- 需要進行最低限度程式設計。
- 讓您專注於以完美的方式撰寫說明文件。
缺點：
- 缺少 CSS 的控制權。
- 可能沒有最佳社群支援。
- 可能不支援 MDX。
= 使用 MKDocs 這提供了另一個 Markdown 解決方案。
優點：
- 同樣需要花少量程式碼編寫程式碼 (同樣適用)。
- 編寫更多，減少程式碼的做法。
缺點：
- 缺少 CSS 的控制權。
- 可能無法提供完善的社群支援，
- 使用 Python；日後可能需要啟用 Amazon S3 執行個體。
= 使用 VueJS +StorybookJS 此方法常用於 Vocabulary 及其姐妹存放區。
優點：
- 根據過往的工作經驗，持續使用保證可以正常運作的技術。
- 熟悉程式碼集。
- 沒有專業的技術。
缺點：
- 也可以針對相同用途提供較簡單的選項。
總結來說，我想採用「VueJS+Storybook」方法 (HTML、CSS、JS) 的做法似乎最合適，因為我也非常瞭解。然而，這也表示我們將逐步開發這個應用程式。使用 CC-Vocabulary 元件時，理論上也相當直觀。然而，為了決定說明文件的結構，我們應必須審慎考量閱讀文件說明文件中將內容劃分成各種子標題的方式。Semantic-UI 網站 (使用 StoryBook) 外觀非常簡約，而且只要點按幾下，就能輕鬆瞭解內容，因此我對 Semantic-UI 網站留下深刻印象。除了 Semantic-UI 外，我也看過 Material Design、 Primer、Bootstrap、Carbon Design 等，做為工作用的 UI 樣式指南和設計系統。我們也會查詢現成的 Jekyll 說明文件主題，從中汲取靈感。