本頁面包含 Google 技術文件季度接受的技術寫作專案詳細資料。
專案摘要
- 開放原始碼組織：
- Linux 基金會
- 技術撰稿人：
- boron
- 專案名稱：
- 重新設計說明文件代管和產生機制，並重新架構入門頁面和開發人員指南。
- 專案長度：
- 標準長度 (3 個月)
Project description
摘要：
說明文件的設計目的，是協助使用者和開發人員使用產品或服務。良好的說明文件非常重要，因為這能讓使用者瞭解如何使用軟體、軟體功能、提示、技巧，以及解決使用軟體時遇到的常見問題。這麼做也可以降低支援成本，並成為產品的企業和開放原始碼身分：良好的說明文件是產品和開發人員團隊健康的象徵。
沒有良好的說明文件，使用者可能不知道如何有效且有效率地執行上述操作。文件是確保產品成功的關鍵，因為良好的溝通是任何業務或產品的核心，而優質的文件正是將這項溝通內容放入可管理的架構，讓所有人都能成功使用。
每個說明文件網站都需要良好的建構和代管工作流程管道。在 AGL 這類擁有多個版本和大量詳細說明文件的機構中，說明文件檔案 (Markdown) 散布在多個存放區，因此維護和更新這些檔案的工作會變得非常複雜且耗時。
目前狀態：
- AGL 文件網站是以從各種存放區擷取的 Markdown 檔案集合為基礎。
- 文件頁面目前是透過 cordova 專案的引擎，以 Markdown 個別來源代管文件頁面。
- 這會導致說明文件建構和代管程序的四個存放區設定：
- 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]：一般文件、指南的來源 (Markdown [https://github.com/automotive-grade-linux/docs-sources/tree/master/docs])。
- Docs-gh-pages [https://github.com/automotive-Grade-linux/docs-gh-pages]：為說明文件網站部署的 GitHub 網頁存放區 [https://gist.github.com/growupboron/docs.automotivelinux.org]。
- 在 docs-tools [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]。book yaml 檔案包含遠端存放區中 Markdown 檔案的所有網址。
- 只要擷取所有 Markdown 檔案，工具就會處理，並在相應部署的 docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] 中產生 AGL 文件網站。
- 目前的管道維護程序對使用者和開發人員來說都容易理解，對新貢獻者來說更是如此。這個工作流程管道 (建構與代管) 可以簡化和簡化，讓開發人員專心處理說明文件，不必費心維護說明文件的產生與部署工作流程。