本页面详细介绍了 Google 文档季计划接受的技术文档项目。
项目摘要
- 开源组织：
- The Linux Foundation
- 技术文档工程师：
- boron
- 项目名称：
- 重新设计文档托管和生成流程，并重组入门页面和开发者指南。
- 项目时长：
- 标准时长（3 个月）
项目说明
摘要：
文档旨在帮助最终用户和开发者使用产品或服务。良好的文档非常重要，因为它可以为用户提供一个学习如何使用软件、软件功能、技巧和窍门，以及解决使用软件时遇到的常见问题的途径。此外，它还可以降低支持成本，并且是产品企业和开源身份的一部分：良好的文档是产品和开发者团队健康状况的标志。
如果没有良好的文档，用户可能不知道如何高效地完成上述操作。文档在确保产品成功方面可以发挥关键作用，因为良好的沟通是任何企业或产品的核心，并且永远都是如此，而良好的文档只是将这种沟通置于一个可管理的框架中，每个人都可以访问该框架以取得成功。
每个文档网站都需要良好的构建和托管工作流流水线。在 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 文件自动生成技术网站的工具。
- Docs-sources [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]：为文档网站 [https://gist.github.com/growupboron/docs.automotivelinux.org] 部署的 GitHub Pages 代码库。
- 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 包含指向所有 book yaml 文件的链接，它会从远程代码库提取所有 book 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 文档网站，并相应地进行部署。
- 维护流水线的当前流程对用户和开发者（尤其是新贡献者）不太友好。可以大大简化和精简此工作流流水线（构建和托管），以便开发者专注于文档部分，而不是维护文档生成和部署工作流。