创建项目报告

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

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

提交项目报告

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

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

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

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

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

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

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

项目报告的要求

请考虑以下要求:

  • 通过链接所指向的内容,必须能够轻松识别您在文档使用季期间完成的作品,即您做出的更改或编写的新文档。
  • 作业应存放在稳定的位置。提交后,网址将无法更改。
  • 他人应该能够使用链接目标处(或引用自)的内容在您的作品的基础上进行构建。

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

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

您无需执行所有(或任何)操作,但您可以通过以下几种方式满足这些要求:

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

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

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

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

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

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

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

  • 指向所做更改的统一或情境差异的链接。请务必添加一个包含您的技术写作项目名称和您的身份的标题,以便于他人使用该标题。

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

请勿执行以下操作:

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

面向导师

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

请检查以下事项:

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

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