本页面包含有关 Google 文档季可接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- Cloud Native Computing Foundation (CNCF)
- 技术文档工程师：
- Shriti
- 项目名称：
- 改进 SMI 及相关服务网格的文档
- 项目时长：
- 标准时长（3 个月）
Project description
服务网格技术的本质上是通过满足您的所有安全、管理和监控需求，为日益增多的服务提供价值。服务网格接口 (SMI) 为最常见的服务网格使用场景（流量政策、遥测和迁移）定义了一组 API，并支持服务网格之间的兼容性。服务网格是专用基础架构层，用于在微服务环境中处理服务间通信。这些接口的标准化将提供更好的最终用户体验，因此，这是 SMI 和相关服务网格的未来目标。
现状：
用户指南： SMI 是一个相对较新的沙盒项目，已于 2020 年 4 月捐赠给 CNCF。因此，最终用户文档中缺少该项目。 Meshery 是一种服务管理平面，针对各种服务进行性能基准测试，有助于采用、配置、运营和管理不同服务网格的性能，同时整合了在任何服务网格上运行的应用的指标收集和显示。因此，我想从 Meshery 的指南入手，它将作为整个 SMI 用户社区的起点。
用户教程： 在现有的 SMI 平台中，示例应用 Learn Layer5 目前既可用作 SMI 的学习设备，也可用作执行 SMI 规范验证的示例应用。但除此之外，SMI 项目完全缺少最终用户教程，由于项目的技术性较高，这会严重阻碍。Meshery 是一款完美的应用，能够展示 SMI 及相关服务网格的优势和用法，因此我将使用它作为展示 SMI 功能的基础工具。
API 文档：目前不存在。SMI 和各种相关项目均在平台上定义其 API 端点；例如，Meshery 的端点在 server.go (https://github.com/layer5io/meshery/blob/master/router/server.go) 中定义，但它们未对外部进行充分评论或记录。这可以通过关于 API 的实用文档来解决，并且可以通过添加可让用户测试其端点和预览其功能的方法来改进。
分析：
创建用户教程是为了让用户能够参与软件并进行测试运行。它们需要具有互动性和美观性才能吸引用户的注意力，最重要的是，还要易于使用。
但是，对于编写或托管用户指南，建议采用更成熟的格式，因为用户指南通常可用作参考指南或快速解决问题。它们不应具有互动性，而是需要结构合理的设计，并侧重于提高清晰度、连贯性和良好的用户体验。
若要解决此问题，可以在 Jekyll 的帮助下，使用 Google Codelab 和独立的用户指南分别制作用户教程，最后将这些教程与 API 文档集成在一起，以便为最终用户和未来的协作者提供全面的体验。
目标受众群体：SMI 项目为其下的所有项目提供部署和运营实践、学习环境和性能基准。它同时满足个人和组织的需求。
用户指南：我将以新手用户为目标受众群体，不假设用户已有 IT 知识。 目标：新手用户 原因：主要用作大量参考指南，需要随时间更新。其中包括深入的说明和实用提示，以确保用户拥有设置和使用服务网格所需的所有信息。您可以根据需要添加视频、图片、屏幕截图和 GIF，让“导视”更具吸引力且更便于用户使用。
用户教程： 目标：新手用户 原因：教程的重点是让教程具有吸引力和美感，以吸引用户的注意力，并使软件能够顺利测试运行，这将有助于更好地了解服务网格界面。
API 端点文档： 目标：高级用户 原因：本部分将重点介绍如何使用服务网格的更复杂的功能，这更适合具备基本 IT 知识的高级用户的兴趣。 高级用户需要寻找简洁的教程，也可以在需要时用作参考指南。端点文档的编写方式应该能够在不影响其准确性或一致性的情况下轻松更新。最好是自动执行的过程。
资源： 用户教程：Google Developers Codelab - 用于制作互动式、全面的最终用户教程。 优点： - 可以生成沙盒教程。 - 采用亲自动手实践的方法。 - 使用 Google 文档编写，支持 Markdown 文本。 - 可以使用 Google Analytics（分析）进行监控 - 轻松观察用户流量。 - 易于使用。制作美观有趣的教程，让用户无需任何直接投资即可直接与软件互动。
CLaaT（Codelab 即 Thing）项目可增强并轻松部署 Google Codelab。CLaaT（Codelab 即 Thing）项目是一个命令行工具，可用于将使用 Markdown 以 Google 文档编写的教程转换为 Codelab (HTML) 格式。
用户指南： Jekyll - 此处提供的 Meshery.io 文档文档托管在 Jekyll 上，并使用 Docsy Jekyll 主题。它使用 Markdown、liquid、HTML 和 CSS 来生成可托管的静态网站，并在 Ruby 开发环境中运行。 优势： - 可以直接从 GitHub 代码库托管网站。 - 这是一个得到充分支持且社区非常活跃的项目 - 用户指南和增强功能可轻松添加到现有的 SMI 和 Meshery 文档中，无需费心迁移到其他平台。
API 文档：Swagger（或者 Swaggo）将用于创建 SMI 和 Meshery 的 API 文档。是编写 API 文档的绝佳解决方案。 好处： - 基于 API 设计的文档：确保您的文档随着 API 的发展而不断更新。 - 基于 API 设计的文档：可根据 API 定义自动生成。 - 维护多个文档版本 - 自定义 API 设计
项目目标： - 使用 Google Developers Codelab 以 Meshery 作为工具，为 SMI 和相关服务网格创建互动式最终用户教程。 - 创建最终用户指南，使用 Jekyll 构建服务网格。 - 使用 Swagger 为 SMI 生成 API 端点文档。 - 打造由社区推动的项目，以便未来和现有用户或开发者能够在 SMI 社区的指导和管理下，轻松继续向项目中添加内容。
时间表： 您可在此处找到建议的时间表： https://docs.google.com/document/d/1If2mtBdWZer4qrh66NfXOWBx_3-tiA09jnoPMqy2lqs/edit#bookmark=kix.j1b6m64eubsl
结构： 您可以访问以下网址，找到建议的《用户指南》结构： https://docs.google.com/document/d/1A3YYAMUTe06MojNWo8hdF4KZbvr-qVaaA2myzWeshHQ/edit?usp=sharing
为什么是此项目？ 服务网格社区正在以极快的速度扩张，这得益于其最近以沙盒项目的形式集成到 CNCF 中。然而，该项目正面临着大量文档问题，对最终用户和开发者来说都是如此。 我过去使用过各种服务网格，包括使用 EmojiVoto 应用的 linkerD、使用 Istio 及其 bookinfo 应用，以及 Hashicorp 的 Consul。我还尝试了 SMI 流量分配，并在服务网格配置中实现了各种验证规则。这个学习过程很有趣，但技术性很强，对于希望迈出进入服务网格社区或将服务网格用于自己的个人或专业项目的新用户和开发者来说，学习过程可能会令他们望而却步。我希望通过有效且文档完备的指南和教程来弥合这一差距。