本页面包含有关 Google 文档季可接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- gRPC - 网关
- 技术文档工程师：
- iamrajiv
- 项目名称：
- 重构 gRPC-Gateway 的现有文档网站
- 项目时长：
- 标准时长（3 个月）
Project description
摘要：
用户文档网站旨在帮助最终用户使用产品或服务。优秀的用户文档网站非常重要，因为它为用户提供了了解如何使用该软件及其功能、提示和技巧的途径，并解决使用该软件时遇到的常见问题。这还可以降低支持成本，并且是产品企业身份的一部分。出色的用户文档网站象征着产品（开发者团队）的健康发展。如果没有优秀的用户文档网站，用户可能不知道如何有效且高效地完成上述操作。在确保产品的成功方面，用户文档网站可以发挥关键作用，因为良好的沟通是任何企业或产品的核心，并将始终是核心，而出色的文档只需要进行沟通，并将其放入一个易于管理且人人皆可访问的框架中。
在撰写本文时，gate-Gateway 代码库已经产生了大约 1200 次分支，有 184 人为该代码库贡献了代码，这表明世界各地的许多人都在使用 gRPC-Gateway，并且可能想要阅读其用户文档，以获得有关如何使用 gRPC-Gateway 的指导。但是，gateway 用户文档和文档网站目前已过时且不完整，并且 gRPC-Gateway 社区希望使用此项目来重构现有的文档网站，以改进其文档网站，使最终用户在使用 gRPC-Gateway 时获得无缝体验。
当前状态：
目前，gRPC-Gateway 文档网站存在两个主要问题：
• 第一个问题是文档网站不好而且已过时，因为所用网站和主题的样式和结构已过时、不完整、难以浏览或查找信息，无法涵盖优质文档网站的许多功能。重构现有文档网站 gRPC-Gateway 将包括设置网站样式、添加文档搜索等功能、改进网站的界面、在适当的边栏中整理教程和示例，以及通过设计新的流程图和图片来更新现有的流程图和图片等。这是我的主要目标，我的工作将更多地基于现有 Google 文档网站的样式和结构调整。
• 第二个问题，需要重构 gRPC-Gateway 的现有文档、教程和示例等，方法是移除文件中排版和语法错误，适当对齐 Go 代码段，并根据 Gofmt 格式重构 Go 代码段。此外，如果可以，我们可以根据需要添加更多文档、教程和示例，或者在重构后重复使用现有文件。这是我的次要目标，在我完成主要目标（即现有 Google 文档网站的样式和结构调整）后会执行此操作。
为什么我们提议的 Google 文档网站在现有网站的基础上会有所改进？
提议的用户文档网站的结构旨在改进，确保提高效率、一致性，使最终用户安心无忧。新版本具有风格鲜明的部分和功能，包含文字指南及其相关的流程图和图片，看起来更加出色，界面也更加美观。
gRPC-Gateway 文档很好地介绍了方法和示例。但它仍然使用旧的 Jekyll 主题，而现在我们拥有更好的 SSG（静态网站生成器）Jekyll 主题。此外，开发者还需要重新构建页面，通过添加新的示例和教程、更新和重写之前的内容，使页面对用户更有帮助。
提议的目标和构想的结构和路线图：
此项目的主要目标：-
上述目标和提示可通过以下方式实现：-
将 Current Jekyll 主题更改为更优质、可靠的主题。再次使用 Jekyll 主题的原因在于，维护者可以轻松贡献和了解项目的工作流，因为他们已经知道现有的 Jekyll 框架和主题，而这些框架和主题与新的 Jekyll 主题类似。
在了解了互联网上的不同 Jekyll 主题后，我发现此 https://idusercontentbewriting.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-网关页面：-
团队版块中应包含所有贡献者的列表 快速链接和版本说明、将添加最新博客以吸引用户，让他们阅读当前的 gRPC-Gateway 新闻。
• 博客、版本说明和教程页面：-
我认为网站应该提供博客选项。这样，他们就可以轻松地传达相关新闻和消息。教程页面将包含一些热门演讲和文章，阐明 gRPC-Gateway API 和概念。贡献者可以在教程页面中添加教程链接。
完成上述任务后，在 v2 分支中更新相同的更改，甚至使用 gRPC-Gateway 的主分支进行更改。
此项目的次要目标：-
需要进行其他更改，才能使 gRPC-Gateway 文档更可靠且更易读：
• 在 gRPC-Gateway 的所有现有文件中，更正了语法和排版错误，并整理网站中的链接和帖子并进行了整理。
• 如果需要在 gRPC-Gateway 中添加更多文档和内容，因为大多数功能的文档都非常简短，例如网站上有关 AWS、背景和使用情况的文档部分，等等。
• 根据 Gofmt 格式重构 Go 代码段 gRPC-Gateway
完成上述任务后，在 v2 分支中更新相同的更改，甚至使用 gRPC-Gateway 的主分支进行更改。
为什么我是此项目的合适人选：
我认为自己是该项目的合适人选，因为：-
• 我有完善组织文档的经验，可以使用任何版本控制系统，因此在 GitHub 上执行命令不会成为问题。 • 此外，推动我开展一些能够为人们创造价值的项目是我的动力所在。 我相信，如果您希望某人以尽可能高效的方式完成某件事，您可以记录下来。通过记录您的流程，您可以确保所有相关人员都能提高效率、一致性并让他们安心无忧。• 我熟悉 gRPC-Gateway 的工作流和代码库，因为我在过去两个月为 gRPC-Gateway 贡献了代码，并且合并了 11 个 PR。