本頁面包含 Google Season of Docs 接受的技術寫作專案詳細資料。
專案摘要
- 開放原始碼機構：
- The Linux Foundation
- 技術撰稿人：
- 硼
- 專案名稱：
- 重新製作說明文件代管和產生功能，並重整入門頁面和開發人員指南。
- 專案長度：
- 標準長度 (3 個月)
Project description
摘要：
說明文件旨在協助使用者和開發人員使用產品或服務。良好的文件非常重要，因為使用者可以透過文件瞭解如何使用軟體、軟體功能、訣竅和秘訣，以及解決使用軟體時遇到的常見問題。此外，這也有助於降低支援成本，並成為產品的企業和開放原始碼身分識別的一部分：優質說明文件是產品和開發團隊健全的指標。
如果沒有優質說明文件，使用者可能不知道如何有效率地完成上述事項。文件在確保產品成功方面扮演關鍵角色，因為良好的溝通是任何企業或產品的核心，而且永遠都是。優質文件只是將這類溝通內容放入可管理的架構，讓所有人都能存取，進而獲得成功。
每個說明文件網站都需要良好的建構和代管工作流程管道。在 AGL 這類組織中，由於有多個版本和大量詳細說明文件，說明文件檔案 (Markdown) 分散在多個存放區，因此維護和更新作業非常複雜且耗時。
目前狀態：
- AGL 文件網站是以從各種存放區擷取的 Markdown 檔案集合為基礎。
- 目前文件頁面以 Markdown 格式託管在個別來源中，並使用 Cordova 專案的引擎。
- 這會導致四個存放區設定，用於說明文件建構和代管程序：
- Docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate]：包含 Jekyll 網站範本。
- Docs-tools [https://github.com/automotive-grade-linux/docs-tools]：內含可從 Markdown 檔案自動產生技術網站的工具。
- 文件來源 [https://github.com/automotive-grade-linux/docs-sources]：一般文件和指南的來源 (markdowns [https://github.com/automotive-grade-linux/docs-sources/tree/master/docs])。
- Docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages]：已部署說明文件網站 [https://gist.github.com/growupboron/docs.automotivelinux.org] 的 GitHub 頁面存放區。
- 文件工具 [https://github.com/automotive-grade-linux/docs-tools] 提供的工具 (指令碼) 會根據 docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] 中的 fetched_files.yml，負責收集所有 Markdown 檔案並套用範本。
- 目前生成 agl 說明文件網站的工作流程：current_workflow [https://drive.google.com/file/d/1OSwkVWFcsajgCOjbtdPf42EIfpidUJ0U/view?usp=sharing]
- section_version.yml 包含所有書籍 YAML 檔案的連結，接著會從遠端存放區擷取所有書籍 YAML 檔案，並存放到 docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate]。書籍 YAML 檔案包含遠端存放區中所有 Markdown 檔案的網址。
- 擷取所有 Markdown 檔案後，工具會處理這些檔案，在 docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] 中產生 AGL 文件網站，並相應地部署該網站。
- 目前維護管道的程序對使用者和開發人員並不友善，尤其是新貢獻者。這個工作流程管道 (建構及代管) 可以大幅簡化及精簡，讓開發人員專注於文件部分，而非維護文件產生和部署工作流程。