本頁針對 Google 系列文件接受的技術撰寫專案提供詳細資料。
專案摘要
- 開放原始碼機構：
- Linux 基金會
- 技術文件撰寫者：
- boron
- 專案名稱：
- 重整說明文件代管、產生和重組作業的入門指南和開發人員指南。
- 專案長度：
- 標準長度 (3 個月)
Project description
摘要：
文件旨在協助使用者和開發人員使用產品或服務。優質說明文件非常重要，因為這可讓使用者有機會瞭解如何使用軟體、相關功能、提示和秘訣，以及解決使用軟體時的常見問題。同時可降低支援費用，且屬於產品的公司和開放原始碼身分，優質文件代表產品和開發團隊的健康狀態。
如果沒有優質文件，使用者可能就無法有效率地執行上述操作。文件在確保產品成功與否扮演著關鍵角色，因為良好的溝通絕對是任何企業或產品的核心，而優質的文件則能完成溝通，並將其運用在易於管理的架構中，讓所有人都能存取所需資料。
每個說明文件網站都需要完善的建構和託管工作流程管道，在 AGL 這類機構中，具有多個版本和大量勞動性文件，因此說明文件檔案 (標記) 分散在多個存放區中，為維護及更新這些項目的任務相當複雜且耗費大量時間。
目前狀態：
- AGL 文件網站採用從各種存放區擷取的 Markdown 檔案集合。
- 文件網頁目前透過 Cordova 專案的引擎，由個別來源代管。
- 這會使文件建構和代管程序的四個存放區設定：
- Docs-webtemplate [https://github.com/automotive-Grade-linux/docs-webtemplate]：包含 Jekyll 網站範本。
- Docs-tools [https://github.com/automotive-Grade-linux/docs-tools]：內含可自動從 Markdown 檔案產生技術網站的工具。
- Docs-sources [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 頁面存放區。
- docs-tools [https://github.com/automotive-Grade-linux/docs-tools] 中的工具 (指令碼) 會根據 docs-webtemplate [https://github.com/automotive-Grade-linux/docs-webtemplate] 中的 extracted_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]。Book YAML 檔案含有遠端存放區中 Markdown 檔案的所有網址。
- 擷取所有 Markdown 檔案後，會在相應的 docs-gh-pages [https://github.com/automotive-Grade-linux/docs-gh-pages] 中產生 AGL 文件網站的工具程序。
- 目前的管道維護程序對使用者和開發人員來說較不容易理解，尤其是新貢獻者更是如此。這個工作流程管道 (建構和託管) 可簡化及簡化，讓開發人員能夠專心處理說明文件部分，不必維護文件的產生和部署工作流程。