创建项目报告

当前阶段：
2020 季 Google 文档计划已于 2021 年 3 月 15 日结束。请参阅时间轴。

本页面包含面向技术文档工程师的指南，说明如何在完成今年文档季的工作后创建项目报告。

提交项目报告

当项目敲定阶段开始后，您可以通过填写技术作者指南的“项目敲定”部分中提供的表单来提交项目报告。

要包含在项目报告中的信息

本部分介绍了您可以在项目报告中提供的信息类型。项目报告表单将包含自由文本字段和选择题。

提供一个指向您所完成作品的说明的链接。

该链接应指向一个文档，其中包含已完成的工作的简短说明、开源项目合并到其代码库的文档、项目的当前状态摘要以及挑战和经验的列表。

该链接会显示在网站上发布的文档季搜索结果中。 发布的结果展示了您在此计划期间完成的工作。发布的结果也是您在简历中回顾您的作品的绝佳方式。

在提交项目报告之前，您应该与导师分享您的链接并请求审核。

项目报告的要求

请考虑以下要求：

  • 通过链接所指向的内容，必须能够轻松识别您在文档使用季期间完成的作品，即您做出的更改或编写的新文档。
  • 作业应存放在稳定的位置。提交后，网址将无法更改。

  • 他人应该能够使用链接目标处（或引用自）的内容在您的作品的基础上进行构建。

    • 如果您的工作已完成 100%，其他人应该可以使用它。
    • 如果您的工作并没有 100% 完成，应该清楚地知道还剩下什么。

关于如何描述作品的正面示例

您无需执行所有（或任何）操作，但您可以通过以下几种方式满足这些要求：

  • 创建博文、网页或公共 GitHub gist，描述您已完成的工作，并链接到您已提交的提交内容和处理的代码库。如果项目仍有要完成的工作，请添加对相应工作的说明。您还可以分享精彩集锦或具有挑战性的作品。

    这是最佳选项，因为它可让您轻松包含大量信息。很好，因为它清晰地展示了您所做的工作，并方便他人使用和理解您的贡献。

  • 如果使用 GitHub，并且您的所有工作都由单个拉取请求涵盖，您可以使用该链接。

    • 确保拉取请求说明详细说明。
    • 确保说明中明确指出该作品适用于文档季。
    • 如果文档剧季结束后拉取请求需要执行更多工作，请确保在文档上一季的提交内容中注明这一点。
    • 这种提供项目报告的方法的好处是，您可以将变更日志、提交列表和审核备注集中到一处。

  • 如果您的 GitHub 代码库是《文档季》的单一用途，请添加包含工作详细信息的 README 文件。

  • 在 Google 云端硬盘中创建一个公共文件夹，并添加您创建的所有补丁。

  • 使用 Google 表格创建公开的电子表格，并列出您的所有提交内容。

  • 指向公开问题跟踪器中的单个问题的链接，其中应明确提及您的工作和任何其他适当的内容。该问题应跟踪您已完成的所有工作。请确保问题列出了所有提交内容，或者确保可以通过其他方式轻松找到提交内容。

  • 指向所做更改的统一或情境差异的链接。请务必在标题中包含您的技术写作项目名称和您的身份，以便对他人非常有用。

关于如何描述作品的反面示例

请勿执行以下操作：

  • 链接到包含整个项目的源代码或您的工作目录的 tarball 或 zip 文件。
  • 指向项目主要源代码库顶部的链接。 例如，如果您使用的是 cpython，则此链接无用：https://github.com/python/cpython。
  • 指向项目源代码库的克隆的链接。 这使您很难看出您的更改内容，因为您的作业混在一起了其他人的工作。
  • 指向您在“文档季”网站上的项目说明的链接。

面向导师

请帮助技术文档工程师创建适当的项目报告。在您自行评估技术文档工程师的工作之前，请务必执行此操作。

请检查以下事项：

  • 提交内容必须符合上述要求。
  • 提交材料必须说明完成的工作、满足的要求以及做出任何具体决定的原因。

《文档季》的概念并不是技术文档写手大量编写文档，该工作可能对托管开源项目有用，这一点非常重要。