本页面包含有关 Google 文档季可接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- Linux 基金会
- 技术文档工程师：
- boron
- 项目名称：
- 重新构建文档托管和生成文档，重构入门页面和开发者指南。
- 项目时长：
- 标准时长（3 个月）
Project description
摘要：
该文档旨在帮助最终用户和开发者使用产品或服务。文档优秀很重要，因为它为用户提供了学习如何使用软件及其功能、提示和技巧的途径，并能够解决使用软件时遇到的常见问题。这样做还可以降低支持成本，并且是产品企业和开源身份的一部分：良好的文档说明产品和开发者团队是否健康。
如果没有好的文档，用户可能不知道如何有效且高效地完成上述操作。在确保产品取得成功方面，文档起着至关重要的作用，因为良好的沟通是任何业务或产品的核心，并将一直是关键。出色的文档需要这种沟通，并将其放入一个易于管理且人人都能访问的框架中。
在 AGL 这样的组织中，每个文档网站都需要一个良好的构建和托管工作流流水线。在 AGL 这样的组织中，文档文件 (markdown) 分布在多个代码库中，这使得维护和更新任务极其复杂且耗时。
现状：
- AGL 文档网站基于从各种代码库获取的一系列 Markdown 文件。
- 文档页面目前托管在各个源代码中，使用 cordova 项目的引擎作为 Markdown。
- 这会为文档构建和托管流程设置四个仓库：
- Docs-webtemplate [https://github.com/automotive-grad-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-grad-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 文档网站。
- 当前的维护流水线流程不利于用户和开发者，尤其是新贡献者。这种工作流管道（构建和托管）可以简化和简化，使开发者更能专注于文档部分，而不是维护文档生成和部署工作流。