本页面包含 Google 文档季接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- gRPC-Gateway
- 技术文档工程师：
- iamrajiv
- 项目名称：
- 重构 gRPC-Gateway 的现有文档网站
- 项目时长：
- 标准时长（3 个月）
Project description
摘要：
用户文档网站旨在协助最终用户使用产品或服务。提供一个优质的用户文档网站非常重要，因为它为用户提供了一个途径，让他们可以了解如何使用该软件、其功能、提示和技巧，以及解决使用该软件时遇到的常见问题。这还可以降低支持成本，并成为产品企业形象的一部分。用户文档网站的质量反映了产品和开发者团队的健康状况。如果没有良好的用户文档网站，用户可能不知道如何高效地执行上述操作。用户文档网站在确保产品取得成功方面可以发挥关键作用，因为良好的沟通一直是任何业务或产品的核心，而优秀的文档正是将这种沟通纳入一个可管理的框架中，使人人都能访问，从而取得成功。
在撰写本文时，gRPC-Gateway 代码库已被分叉大约 1200 次，有 184 人为此代码库做出了贡献，这表明世界各地有许多人使用 gRPC-Gateway，并且可能希望阅读其用户文档，以获取有关如何使用 gRPC-Gateway 的指导。不过，gRPC-Gateway 用户文档和文档网站目前已过时且不完整，gRPC-Gateway 社区希望通过此项目重构现有文档网站，以改进其文档网站，让最终用户在使用 gRPC-Gateway 时获得顺畅的体验。
当前状态：
目前，gRPC-Gateway 文档网站存在两个主要问题：-
• 第一个问题是文档网站糟糕且过时，即网站和所用主题的样式和结构已过时、不完整、难以浏览或查找信息，并且未涵盖优质文档网站的许多功能。重构 gRPC-Gateway 的现有文档网站将包括设置网站样式、添加文档搜索等功能、改进网站界面、在适当的边栏中整理教程和示例，以及通过设计新的流程图和图片来更新现有流程图和图片等。这是我的首要目标，我的工作将更多地基于现有文档网站的样式和重构。
• 第二个问题是，需要重构 gRPC-Gateway 的现有文档、教程和示例等，具体方法是移除文件中的拼写和语法错误，使 Go 代码段正确对齐，并根据 Gofmt 格式重构 Go 代码段。此外，如果是，我们可以根据需要添加更多文档、教程和示例，或者在重构现有文件后重复使用这些文件。这是我的次要目标，我会在完成主要目标（即对现有 Google 文档网站进行样式设置和重构）后再进行此操作。
为什么我提议的 Google 文档网站比当前网站更出色？
我们提议的用户文档网站的结构将提升和确保最终用户的效率、一致性和后顾之忧。这样可以让界面看起来更美观，并通过采用风格统一的版块和功能，在其中添加书面指南及其相关的流程图和图片，从而提升界面效果。
gRPC-Gateway 文档对该方法和示例进行了详细说明。但它仍在使用旧版 Jekyll 主题，而现在我们有更好的 SSG（静态网站生成器）Jekyll 主题。此外，我们还需要对页面进行重构，通过添加新示例和教程以及更新和重写之前的内容，使其对用户更有用。
拟议目标和想法的结构和路线图：
此项目的主要目标：-
上述目标和想法可通过以下方式实现：-
将当前的 Jekyll 主题改为更出色、更稳健的主题。之所以再次使用 Jekyll 主题，是因为维护者已经熟悉与新 Jekyll 主题类似的现有 Jekyll 框架和主题，因此可以轻松做出贡献并了解项目的工作流程。
在浏览互联网上的各种 Jekyll 主题后，我发现 https://idratherbewriting.com/documentation-theme-jekyll/ 主题套件最适合 gRPC-Gateway 文档网站，因为它具有以下特性：
• Markdown： 这样技术文档工程师就不必担心安装问题。他们可以直接在 .md 文件中编写内容。任何人都可以点击网站上显示的“修改”按钮（新功能），并贡献自己的力量（在 GitHub 中修改/建议更改网页），以便改进该网页。这将吸引用户添加新内容或修改内容来改善内容。
• 文档搜索：- 用户应设置搜索框，以便他们轻松快速地找到相关内容。
• 评论区：-用户可以选择对帖子和教程发表评论并分享自己的看法。他们可以查看其他人对项目文档的意见。
• 新版本说明和博客：- 网站应更新，以发布新的博文以及有关当前开发和路线图的新闻。因此，着陆页上应显示这类博客。
• 快速开发：大多数 SSG（静态网站生成器）框架都在服务器中运行，文件中的更改会立即反映在界面中。此外，部署和构建流程也应简单易行。今后，如果我们想更改框架，可以使用这样应该就很简单了。大多数框架都支持 Markdown 编写，因此只需移动 .md 文件并进行少量更改即可。
在这里，我将现有的网站页面拆分为新的网站版块和页面：
• 着陆页：-
着陆页应指出 gRPC-Gateway 的主要功能。
- gRPC-Gateway 使用入门（重定向到用户指南）
- 简单的安装说明（简要命令）
- 为何使用 gRPC-Gateway
- 使用 gRPC-Gateway 的项目
因此，我们的基本思路不是撰写长篇说明，而是在着陆页中显示要点并提供用于了解详细信息的链接。
• gRPC-Gateway 用户指南页面：-
- 安装指南。
- gRPC-Gateway 快速入门。
• gRPC-Gateway 开发者指南页面：-
“开发指南”“贡献指南”“Git 设置”“行为准则”“文档设置”“开发工作流”等指向内部类似的页面。因此，我们需要重构和重新排列所有文件。“主要开发”页面应包含所有这些页面，并且系统会在每个步骤中创建超链接。
•“gRPC-Gateway 简介”页面：-
团队版块中应包含所有贡献者的列表 快速链接和版本说明、最新博客，以吸引用户阅读最新的 gRPC-Gateway 新闻。
• 博客、版本说明和教程页面：-
我认为该网站应提供博客选项。这样，您就可以轻松传达新闻和版本信息。教程页面将包含一些热门演讲和文章，这些演讲和文章会阐明 gRPC-Gateway API 和相关概念。贡献者可以在教程页面中添加其教程链接。
完成上述任务后，在 v2 分支中更新相同的更改，并使其与 gRPC-Gateway 的主分支保持一致。
此项目的次要目标：
为使 gRPC-Gateway 文档更加可靠和可读，还需要进行其他更改：
• 修复语法、排版错误，并针对 gRPC-Gateway 的所有现有文件整理并调整网站中的链接和帖子。
• 如果需要，在 gRPC-Gateway 中添加更多文档和内容，因为大多数功能都有非常简短的文档，例如网站上关于 AWS、背景和使用情况等的文档部分。
• 根据 Gofmt 格式重构 Go 代码段 gRPC-Gateway
完成上述任务后，在 v2 分支中更新相同的更改，并使其与 gRPC-Gateway 的主分支保持一致。
WHY AM I THE RIGHT PERSON FOR THIS PROJECT:
我相信自己适合开展这个项目，因为：-
• 我过去有过改进组织文档的经验，并且可以使用任何版本控制系统，因此在 GitHub 上执行命令不会有任何问题。 • 此外，我喜欢参与能够为用户创造价值的项目。 我认为，如果您希望某人以最有效的方式执行某项操作，就需要记录相关信息。通过记录流程，您可以确保效率、一致性，并让所有相关人员都能高枕无忧。 • 我自过去两个月以来一直在为 gRPC-Gateway 做出贡献，并已成功合并 11 个 PR，因此熟悉 gRPC-Gateway 的工作流和代码库。