本页面包含有关 Google 文档季可接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- GenPipes
- 技术文档工程师：
- shaloo
- 项目名称：
- 在“阅读文档”中设置 GenPipes 文档
- 项目时长：
- 标准时长（3 个月）
Project description
我提议一个三步计划，以实现在“阅读文档”上设置 GenPipes 文档的目标。
第 1 步：POC
以新用户 / 研究人员的身份查看 GenPipes 的现有文档
- 识别缺失的信息、不准确之处
- 建议新的文档主题（如果需要）
- 拟定信息架构映射草稿，以吸引目标受众群体，并侧重于新用户。
（注意：在此步骤中，我们还可能需要 GenPipes 导师提供有关新的 GitHub 代码库设置的输入信息，其中可以托管用于 RTD 的 genpipes 文档。此 GitHub 代码库可用于导入 RTD 构建流水线中的所有文档。这可能需要您深入了解 GenPipes 代码库规则和文档源代码管理准则（如果需要遵循的话）。否则，也可以使用标准 API，afaik。此外，对于 PoC，我还可以使用自己的 GitHub 帐号演示一个示例 RTD 代码库设置，例如，https://gpdocs.readthedocs.io/en/latest/，这是我为此提案创建的一个采样器）
根据上一步中的审核和分析，为提议的 GenPipes 文档结构 / 索引创建一个准框架，并将其发布在 RTD 网站上
- 这涉及创建 GitHub 代码库（例如使用 Sphinx 工具）和基本文档文件
- 这也涉及到新的 TOC 的创建，以便在各个部分 / 信息流中同时考虑到新用户和老用户。
审核 / 审批准系统骨架 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 个月的成效来判断。
此外，我建议大家有其他的项目提案创意：制作 GenPipes 的 3 页简报，以便轻松上手。如今，一个新用户在开始使用 GenPipes 之前，必须突破重重障碍，因为相关文档虽然不错，但零星分布，不利于新用户。我不确定 3 个月内能否完成这项操作，但我也想试试看。
您也可以通过以下网址查看此提案及其生成过程：https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing