本页详细介绍了 Google 文档季收录的技术文案项目。
项目摘要
- 开源组织：
- GenPipes
- 技术文档工程师：
- shaloo
- 项目名称：
- 前往“阅读文档”部分设置 GenPipes 文档
- 项目时长：
- 标准时长（3 个月）
Project description
我提议一个 3 步计划，以实现在“阅读文档”上设置 GenPipes 文档的目标。
第 1 步：PoC
作为新用户 / 研究人员查看 GenPipes 的现有文档
- 找出缺失的信息、不准确的信息
- 建议添加新的文档主题（如有需要）
- 信息架构草图，以吸引目标受众群体为目标，重点关注新用户。
（注意：在此步骤中，我们可能还需要 GenPipes 导师提供有关新 GitHub 代码库设置的反馈，以便托管适用于 RTD 的 GenPipes 文档。此 GitHub 代码库可用于导入 RTD 构建流水线中的所有文档。这可能需要了解 GenPipes 代码库规则和文档源代码管理指南（如果有需要遵循的话）。否则，可以使用标准模式，afaik。此外，为了进行 PoC，我可以使用我的 GitHub 账号演示示例 RTD 代码库设置，例如 https://gpdocs.readthedocs.io/en/latest/（这是我为此提案创建的示例）
根据上一步中的审核和分析，创建拟议 GenPipes 文档结构 / 索引的框架，并将其发布在 RTD 网站上
- 这涉及 GitHub 代码库创建（例如使用 Sphinx 工具）和基本文档文件
- 这还涉及创建新的目录，以便新用户和老用户都能轻松找到各种信息版块 / 流程。
对准系统框架 TOC 进行审核 / 获得批准
在 GenPipes GSoD 评估阶段，我尝试通过在 RTD 上托管的这个样本为 GenPipes 创造价值。请注意，此链接仅用于演示目的，是受保护的链接，尚未在 RTD 上公开列出。无论我是否入围，都可以使用此演示来快速启动 GenPipes RTD 工作。我已将源代码签入 c3g/GenPipes GitHub 代码库。导师 Rola 和 Hector 在之前的 Skype“共享屏幕”讨论中很喜欢它，因此我认为 GSoD 团队可能也想看看。目前只是一个框架，但我计划在 7 月 30 日之前抽出时间对其进行更新。
https://genpipes.readthedocs.io/en/latest/
第 2 步：创建 GenPipes Doc v0.9 文档集
确定哪些当前或现有的 GenPipes 文档可以导入、链接或转换为基于 Sphinx/rst 的文档，以便在 RTD 上托管，同时注意 GSoD 时间表
将确定的文档转换为 rst 格式（如有需要），在适用的情况下创建新文档，尽可能重复使用相关文档。
- 将此初始文档集作为概念验证导入 ReadTheDocs，并将其作为受保护的代码库托管在该平台上。预先添加备注，建议新用户查看 GenPipes 原始文档，直到审核/正式切换为止。
Review/course-correct/update
第 3 步：在 RTD 中优化、审核和发布初稿
在 GenPipes 目录中填写拟议的 GenPipes 新文档结构的详细信息 - 除了前几个文档（GenPipes 自述文件）之外，添加其他文档（概念、教程等）。
在目录中添加了明确的划分，以便新用户、经验丰富的 GenPipes 用户、GenPipes 开发者等各方都能找到所需内容。
建议并讨论通过 RTD（Sphinx build）实现部分自动化的工作流程，探讨用户如何维护和修改 GenPipes 文档集，以及 C3G 是否允许外部文档贡献者执行此操作。这可能需要创建一些类似于编码准则的文档更新准则。可能需要执行更多子步骤。例如，在 GenPipes 文档中在 PR 批准之前自动进行拼写检查。
报告
最后，根据经验、日志和导师的反馈，为 GSoD 创建一份报告。
其他想法
今后（超过 3 个月），如果适用，我可以帮助 GenPipes 进行更长时间的维护。或者，根据需要培训其他人执行此操作。我们可以根据前 3 个月的效果来确定这一点。
此外，我还建议您提供其他项目提案想法，例如创建一份 3 页的 GenPipes 简报，以便用户轻松上手。如今，新用户必须先完成很多任务，然后才能开始使用 GenPipes，因为文档虽然很好，但比较分散，对新用户不利。我不确定这是否能在 3 个月内完成，但我会尽力尝试。
您还可以访问 https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing，查看这项提案及其产生过程（历史记录）