本頁針對 Google 系列文件接受的技術撰寫專案提供詳細資料。
專案摘要
- 開放原始碼機構：
- Kolibri
- 技術文件撰寫者：
- StephDix
- 專案名稱：
- Kolibri 生態系統說明文件樣式和工作流程慣例
- 專案長度：
- 長時間執行 (5 個月)
Project description
摘要
本文件詳細說明瞭學習 Equality 所記錄的 Kolibri 生態系統專案資訊，如何實作樣式指南和工作流程管理。
總覽
我的提案包含四個階段，在第一階段，我會按照軟體開發的 LE 說明文件概念和樣式指南，完成 LE 說明文件樣式指南，當中提供無障礙指南、書寫及格式建議。在第二階段，我將針對 ReadTheDocs 和 GoogleDocs 文件執行品質稽核。稽核計畫整合了檢查清單，以評估是否符合樣式規範。這些檢查清單有助於記錄發現項目，並將變更套用至說明文件。在第三階段，我將介紹 ReadTheDocs 和 GoogleDocs 文件範本的結構、外觀和風格。我會在 Google 雲端硬碟中建立範本和圖片存放區，用於識別各類主要文件類型的範本，以便在後續實作項目中重複使用。我會輔助這項工作建立範本，提交文件問題，方便您在提取要求審查時辨識。最後，我會製作一份貢獻者指南，針對每個協作者分組實用資源，幫助他們提升資訊存取體驗。
目的和範圍
這項實作計畫的用意是改善使用者運用 Kolibri 文件的體驗，並協助團隊成員和協作者製作更優質的文件，並在社群中積極協作。 這項實作適用於 Kolibri Ecosystem 中 ReadTheDocs 和 Google 文件的子集。
適用對象
以導入人員、管理員和使用者為主要目標對象，是 Kolibri 說明文件最重要的消費者。 團隊成員與協作者的次要目標對象，負責製作及使用 Kolibri 說明文件。
目標
Kolibri 生態系統說明文件的內容風格指南和工作流程系統預期使用者會執行以下動作： 使用無障礙語言和一致的版面配置打造容易理解的文件。 保存說明文件的品質做法。輕鬆存取不同說明文件管道中的資訊。強化 Kolibri 開放原始碼社群的合作計畫。
Sources of information
我的資訊來源包括 Kolibri、Kolibri Studio、Kolibri Development RTD 文件和 Google 雲端硬碟的 Kolibri 工具包。
完美的 Radina Matic 是提供暖身活動和專案專屬活動的絕佳協助。她針對組織所稱的「準則」和「指南」概念，以及貢獻者指南是否存在，幫助我整理自己的想法和結論。
軟體
我會在 Google 文件中製作樣式指南草稿。這個文件平台非常適合用來在準備好發布時進行疊代。為了進行品質確保稽核，我將使用 Google 表單執行及評估文件。試算表會儲存表單回應，以便控製文件。我將使用 GitHub 重構 RTD 文件。我曾與 Git、Gitkraken、GitHub 和 Gitlab 合作。我有 Markdown 和一些 RestructuredText 的實務知識。我打算提供修正說明文件，才能繼續學習語法。我將使用 Sharex 工具處理圖片和 GIF。這項工具可以顯示不同的輸出格式，因此我很喜歡這項工具。我會使用圖表製作圖表和圖片版本。圖表軟體與 Google 文件、Google 雲端硬碟和 LibreOffice 完美整合。 說明文件狀態 在探索階段，我修改了大部分的 Kolibri 說明文件。我在專案的大多數說明文件中發現了文法錯誤、拼寫錯誤、版面配置不一致、字體排版和圖片用法不一致，以及容易混淆的文件路徑。以 Kolibri 使用手冊為例，疑難排解部分是子主題，而不是主題。這些資訊是非常重要的，能讓使用者從目錄存取這些資訊。第二種方法則是利用搜尋列和目錄目錄，展開其他主題並找出疑難排解文章。
如要進入「疑難排解」部分，請搜尋該部分或展開「管理 Kolibri」，瞭解「疑難排解」包含在說明文件中。 指南與指南 本專案提案分析了兩份文件：LE Kolibri 使用者說明文件樣式指南和 LE Translation Guidelines。在《LE Kolibri 指南》中，我根據我提議的主題大綱和說明文件計畫，提供了建議和留言，以及其他需要改善的指南。根據 LE 翻譯指南，我根據樣式指南中的建議和現有慣例，變更了格式和樣式。分析期間，我發現在分類為「指南」和「指南」等文件之間存在常見的誤解。
成果
除了建議和註解之外，我也對 LE 翻譯指南進行了品質檢查，並提供了初步的表單，可在品質確保稽核工作中詳細說明。以下是從評估取得的最終評語： ICU 語法 .js 網站的無效連結 建立這些「指南」的格式不正確。 文件僅是「指南」，而非「指南」。字體排版不一致。標題和標題使用方式有誤、不當使用方式或不當使用縮寫。 不當使用替代文字。重複陳述/ 指示。
這兩份文件的調查結果都已納入本提案的「交付項目」中。
專案專屬工作
- LE 使用者說明文件樣式指南建議 (註解)
- LE 翻譯指南，採用新樣式與格式。
- 主題大綱
- 專案時程
- 說明文件工作