本页面包含“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 原始文档，直到获得审核/正式改用为止。
复习/更正课程/更新课程
第 3 步：在 RTD 处优化、审核并发布初稿
在 GenPipes TOC 中填写提议的 GenPipes 新文档结构的详细信息 – 除了前几个文档（GenPipes 自述文件）、概念、教程等外，添加其他文档。
在 TOC 中添加明确的划分界，以称呼新用户、经验丰富的 GenPipes 用户、GenPipes 开发者等。
就如何维护和修改 GenPipes 文档集以及 C3G 是否允许外部文档贡献者进行相关建议，讨论通过 RTD（Sphinx build）实现部分自动化的工作流程。这可能需要为文档更新创建一些准则，类似于编码准则。可能需要更多子步骤。例如，在 GenPipes 文档中在 PR 审批前自动进行拼写检查。
举报
最后，根据经验、日志和导师的反馈创建 GSoD 报告。
其他想法
今后（3 个月以后），如果适用，我可以为 GenPipes 长期提供相关支持。如果需要，也可以培训其他人也这样做。我们可以根据前 3 个月的成效来解决这个问题。
此外，我还推荐了一些其他的项目提案创意：制作一份 3 页的 GenPipes 简报，有助于简化入门流程。如今，新用户必须先经过诸多麻烦，然后才能开始使用 GenPipes，因为相关文档虽然不错，但比较分散，对新用户没有帮助。我不确定能否在 3 个月内完成这项工作，但我也想试试看。
您也可以访问 https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing 以查看此提案及其生成过程（历史记录）