本页面包含 Google 文档季接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- Cloud Native Computing Foundation (CNCF)
- 技术文档工程师：
- Shriti
- 项目名称：
- 改进了 SMI 和相关服务网格的文档
- 项目时长：
- 标准时长（3 个月）
Project description
服务网格技术的本质是通过处理您的所有安全、管理和监控需求，为越来越多的服务提供价值。 Service Mesh Interface (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 的有意义的文档来解决，还可以通过添加用户测试其端点和预览其功能的方式得到增强。
分析：
创建用户教程是为了让用户参与并试运行软件。它们需要具有互动性和美感，以吸引用户的注意力，最重要的是，它们还需要易于使用。
不过，在撰写或托管用户指南时，建议采用更成熟的格式，因为用户指南通常用作参考指南或快速解决问题的途径。这类广告不能具有互动性，而必须结构合理，并且侧重于提高清晰度、连贯性和良好的用户体验。
一个可能的解决方案是，使用 Google Codelab 制作单独的用户教程，并借助 Jekyll 制作独立的用户指南，最后将它们与 API 文档集成，以便为最终用户和未来的协作者提供全面的体验。
目标受众：SMI 项目为其下属的所有项目提供部署和运维实践、学习环境和性能基准。它适用于个人和组织。
用户指南：我将以初学者为目标用户，不会假定用户端已有 IT 知识。 目标对象：新手用户 原因：主要用作庞大的参考指南，需要随着时间的推移进行更新。其中包括深入说明和实用提示，以确保用户拥有设置和使用服务网格所需的所有信息。在需要时添加视频、图片、屏幕截图和 GIF 动图，让指南更具吸引力和易用性。
用户教程： 目标：初级用户 原因：重点是使教程富有吸引力且美观，以吸引用户的注意力并让用户能够顺利运行软件，从而更好地了解 Service Mesh 接口。
API 端点文档： 目标：高级用户 原因：本部分重点介绍如何使用服务网格中更复杂的功能，该功能更符合具备基本 IT 知识的高级用户的需求。 高级用户会寻找简明的教程，以便在需要时用作参考指南。端点文档应以这种方式编写，以便轻松更新，同时又不会影响其准确性或一致性。最好是自动执行此过程。
资源： 用户教程： Google Developers Codelab - 用于制作互动性强且全面的最终用户教程。 优势： - 可以制作沙盒教程。 - 采用实践方法。 - 使用 Google 文档编写，支持 Markdown 文本。- 可以使用 Google Analytics 进行监控 - 轻松观察用户流量。 - 易于使用。制作美观的使用教程，让用户无需任何直接投资即可直接与软件互动。
您可以使用 CLaaT（将 Codelab 作为一个实体）项目增强 Google Codelab 并轻松部署它们。该项目提供了一个命令行工具，用于将使用 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 开发者 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 中。不过，该项目严重缺乏面向最终用户和开发者的文档。我之前曾尝试过各种服务网格，包括将 linkerD 与 EmojiVoto 应用搭配使用、将 Istio 与其 bookinfo 应用搭配使用，以及使用 Hashicorp 的 Consul。我还尝试了 SMI 流量拆分，并在服务网格配置中实现了各种验证规则。学习过程虽然很有趣，但技术性很强，对于希望迈出服务网格社区第一步或将服务网格用于个人或专业项目的新用户和开发者来说，可能会令人望而却步。我希望能够弥合这一差距，而这只能通过高效且文档完善的指南和教程来实现。