Linux Foundation 项目

本页面包含 Google 文档季接受的技术写作项目的详细信息。

项目摘要

开源组织：

Linux 基金会

技术文档工程师：

硼

项目名称：

改进了文档托管和生成方式，并重构了入门页面和开发者指南。

项目时长：

标准时长（3 个月）

Project description

摘要：

文档旨在帮助最终用户和开发者使用产品或服务。好的文档非常重要，因为它为用户提供了一个途径来了解如何使用软件及其功能、提示、技巧，并解决使用软件时遇到的常见问题。这还能降低支持成本，并成为产品的企业和开源身份的一部分：优质文档是产品和开发者团队健康状况的标志。

如果没有良好的文档，用户可能不知道如何高效地执行上述操作。文档在确保产品取得成功方面可以发挥关键作用，因为良好的沟通始终是任何业务或产品的核心，而优质的文档只需将这种沟通纳入一个可管理的框架中，让每个人都能访问，从而取得成功。

每个文档网站都需要一个良好的构建和托管工作流流水线，在像 AGL 这样具有多个版本和大量编写文档的组织中，文档文件（ Markdown）分散在多个代码库中，使得维护和更新任务变得异常复杂和耗时。

当前状态：

• AGL 文档网站基于从各种代码库中提取的一系列 Markdown 文件。
• 文档页面目前托管在各个来源中，以 Markdown 格式使用 Cordova 项目的引擎。
• 这需要为文档构建和托管流程设置四个代码库：
• Docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate]：包含 Jekyll 网站模板。
• Google 文档工具 [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 页面代码库。
• 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]。图书 YAML 文件包含远程代码库中 Markdown 文件的所有网址。
• 提取所有 Markdown 文件后，工具会在 docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] 中生成 AGL 文档网站，并相应地进行部署。
• 目前维护流水线的流程不太方便用户和开发者，尤其是新贡献者。此工作流流水线（构建和托管）可以简化和简化，以便开发者专注于文档部分，而不是维护文档生成和部署工作流。