本页面包含 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 文档网站,并相应地进行部署。
- 目前维护流水线的流程不太方便用户和开发者,尤其是新贡献者。此工作流流水线(构建和托管)可以简化和简化,以便开发者专注于文档部分,而不是维护文档生成和部署工作流。