添加新文档

贡献新文档到 Istio,请执行以下步骤:

  1. 确定受众和信息的预期用途。
  2. 选择您想要贡献的内容类型
  3. 命名标题
  4. 按照文档贡献指南撰写您的贡献。
  5. 将您的贡献提交到 GitHub 存储库
  6. 执行审核流程,直到您的贡献被合并。

确定受众和信息的预期用途

好的文档需要从了解读者的阅读目的,知识面以及希望他们如何处理这些信息开始。否则,您无法确定要提供的信息的范围和深度、 理想结构和必要的支持信息。以下示例描述如何在实际操作中践行该准则:

  • 读者需要执行特定的任务:告诉他们如何识别哪些是需要执行的任务,并以编号步骤列表的形式提供任务细节,而不是简单地概括性地描述任务。

  • 读者在执行任务之前必须理解一个概念:在执行任务之前,请先介绍先决条件并提供指向该信息的链接。

  • 读者需要做出决定:提供必要的概念性信息,以了解何时做出决定,可用选项以及何时选择一个选项而不是另一个。

  • 读者是运维人员,而不是软件工程师(SWE):提供执行脚本,而不是开发人员指南中的代码示例链接。

  • 读者需要扩展产品的功能:提供一个如何扩展功能的示例,并使用简化方案进行说明。

  • 读者需要理解复杂的功能关系:提供一个显示关系的图表,而不是编写大量文字信息供阅读理解。

要避免的最重要也是最常见的错误,是简单地向读者提供您拥有的所有信息,因为您不确定他们需要什么信息。

如果您需要帮助特定内容的受众,我们很乐意在 文档工作组 每两周一次的会议上帮助您并回答您的所有问题。

内容类型

了解受众和所提供信息的预期用途后,您可以选择最能满足他们需求的内容类型。为了方便您选择, 下表提供了受支持的内容类型、预期受众及每种类型文档的实施目标:

内容类型目标受众
概念解释 Istio 相关内容。例如,概念页面描述功能的配置模型并解释其功能。概念页面不包含步骤序列。而是提供指向相应任务的链接。想要了解功能的工作原理的读者仅需具备项目的基本知识。
参考页面提供详尽的技术信息。常见示例包括 API 参数、命令行选项、配置设置和高级过程。参考内容是从 Istio 代码库生成的,并经过 了准确性测试。具有项目高级和深入技术知识的读者,需要特定的信息来完成高级任务。
例子描述一个工作的独立示例,该示例突出显示一组功能特性,Istio 与其他项目的集成或用例的端到端解决方案。 示例必须使用现有的 Istio 安装作为起点。示例必须包括自动测试,因为它们是为技术准确性而维护的。希望自己快速运行示例并进行实验的读者。理想情况下,读者应该能够轻松更改示例以产生自己的解决方案。
任务显示如何使用 Istio 功能实现单个目标。任务包含按步骤序列编写的过程。 任务仅提供对功能的最少说明,但包括指向提供相关背景和知识的概念的链接。 任务必须包括自动化测试,因为它们已经过测试和维护以确保技术准确性。想要使用 Istio 功能的读者。
安装页面着重于完成 Istio 部署所需的安装步骤。安装页面必须包括自动测试,因为它们已经过测试和维护以确保技术准确性。想要完成部署的新旧 Istio 用户。
博客文章专注于 Istio 或与其相关的产品和技术。博客文章属于以下三个类别之一:
  • 文章详细介绍了作者使用和配置 Istio 的经验,尤其是那些表达新颖经验或观点的经验。
  • 突出 Istio 功能的文章。
  • 文章详细介绍了如何使用 Istio 完成任务或实现特定用例。与任务和示例不同,博客文章的技术准确性在发布后不会得到维护和测试。
对项目有基本了解的读者想以更加无拘束的方式,通过案例、实践来了解它。
新闻条目关注有关 Istio 和相关事件的及时信息。新闻条目通常会宣布新版本或即将发生的事件。希望快速了解 Istio 社区中的新变化和新事物的读者。
常见问题解答提供常见问题的快速解答。答案没有介绍任何概念。相反,他们提供了实用的建议或见解。 答案必须链接到文档中的任务,概念或示例,以使读者了解更多信息。有特定问题的读者正在寻找简要答案和资源以了解更多信息。
操作指南着重于解决在实际环境中运行 Istio 时遇到的特定问题的实用解决方案。想要解决有关运行 Istio 或服务网格操作的问题及实现方案。

命名标题

为您的主题选择一个标题,该标题具有您希望搜索引擎查找的关键字。Istio 中的所有内容文件都被命名为 index.md, 但是每个内容文件都存放在用标题关键字命名的文件夹中,并用连字符分隔,所有字母均小写。文件夹名称应尽可能短, 以使交叉引用更易于创建和维护。

将您的贡献提交到 GitHub

如果您不熟悉 GitHub,请参阅使用 GitHub 参与社区活动,以了解如何提交文档更改。

如果您想了解有关发表文稿的方式和时间的更多信息,请参阅分支策略, 以了解我们如何使用分支和 cherry picking 来发布我们的内容。

这些信息有用吗?
您是否有更多建议和改进意见?

感谢您的反馈!