本页面包含“Google 文档季”接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- Linux Foundation
- 技术文档工程师：
- boron
- 项目名称：
- 重新设计托管和生成文档的内容，以及重构入门页面和开发者指南。
- 项目时长：
- 标准时长（3 个月）
Project description
摘要：
文档旨在帮助最终用户和开发者使用产品或服务。优秀的文档很重要，因为它为用户提供了学习如何使用软件及其功能、提示和技巧的途径，并解决使用软件时遇到的常见问题。它还可以降低支持成本，并且是产品企业和开源身份的一部分：好的文档表明产品和开发者团队运行状况良好。
如果没有好的文档，用户可能不知道如何有效且高效地完成上述操作。文档在确保产品的成功方面可以发挥关键作用，因为出色的沟通是所有企业或产品的核心，并且永远都是核心。优秀的文档只不过是成功的沟通，并将其放入一个易于管理的框架中，让每个人都能顺利访问。
每个文档网站都需要一个良好的构建和托管工作流流水线，在像 AGL 这样的组织中，它具有多个版本和大量详细的文档，文档文件 (markdown) 分布在多个代码库中，这使得维护和更新任务变得极其复杂且耗时。
当前状态：
- AGL 文档网站基于从各种代码库提取的一系列 Markdown 文件。
- 文档页面目前使用 Cordova 项目的引擎，以 Markdown 的形式托管在各个来源中。
- 这会为文档构建和托管流程设置四个仓库：
- Google 文档网络模板 [https://github.com/automotive-Grade-linux/docs-webtemplate]：包含 Jekyll 网站模板。
- Google 文档工具 [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])。
- doc-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-grad-linux/docs-tools] 中提供的工具（脚本）负责根据 docs-webtemplate [https://github.com/automotive-Grade-linux/docs-webtemplate] 中的 fetch_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 文档网站。
- 当前的维护流水线流程对用户和开发者而言并不方便，尤其是对于新贡献者而言。这种工作流流水线（构建和托管）可以简化和简化，使开发者能够专注于文档部分，而无需维护文档生成和部署工作流。