添加新文档
要为 Istio 贡献新的文档，只需按照以下步骤操作
- 确定信息的受众和预期用途。
- 选择您希望贡献的内容类型。
- 选择一个标题.
- 按照我们的文档贡献指南编写您的贡献。
- 将您的贡献提交到我们的GitHub 存储库。
- 按照我们的审查流程，直到您的贡献被合并。
确定受众和预期用途
最好的文档从了解目标读者、他们的知识以及您希望他们如何使用这些信息开始。否则，您将无法确定要提供的合适的信息范围和深度、其理想结构或必要的支持信息。以下示例展示了这一原则的实际应用
读者需要执行特定任务：告诉他们如何识别何时需要执行该任务，并以编号步骤列表的形式提供任务本身，而不要只是笼统地描述任务。
读者必须先理解某个概念才能执行任务：在任务之前，告诉他们先决条件信息并提供相关链接。
读者需要做出决策：提供必要的概念信息，以便了解何时需要做出决策，可用的选项以及何时选择一个选项而不是另一个选项。
读者是管理员，但不是软件工程师：提供脚本，而不是开发者指南中代码示例的链接。
读者需要扩展产品的特性：提供一个如何扩展特性的示例，使用简化的场景进行说明。
读者需要理解复杂的功能关系：提供一个显示关系的图表，而不是编写多页内容，因为这些内容读起来很乏味且难以理解。
最重要的是避免常见的错误，即仅仅因为不确定读者需要哪些信息，而提供所有你掌握的信息。
如果你需要帮助确定内容的受众，我们很乐意提供帮助并在文档工作组的双周会议期间回答你所有的问题。
内容类型
当你了解了受众和你提供的信息的预期用途后，就可以选择最能满足他们需求的内容类型。为了方便你选择，下表显示了支持的内容类型、目标受众以及每种类型力求达成的目标
| 内容类型 | 目标 | 受众 |
|---|---|---|
| 概念 | 解释 Istio 的某个重要方面。例如，概念页面描述了某个功能的配置模型并解释其功能。概念页面不包含步骤序列。而是提供指向相应任务的链接。 | 想要仅用项目的基本知识来了解功能如何工作的读者。 |
| 参考页面 | 提供详尽且详细的技术信息。常见示例包括 API 参数、命令行选项、配置设置和高级过程。参考内容是从 Istio 代码库生成的，并经过测试以确保准确性。 | 具有高级和深入项目技术知识，需要特定信息来完成高级任务的读者。 |
| 示例 | 描述一个工作且独立的示例，该示例突出显示一组功能、Istio 与其他项目的集成或用例的端到端解决方案。示例必须使用现有的 Istio 设置作为起点。示例必须包含自动化测试，因为它们是为了技术准确性而维护的。 | 想要快速自己运行示例并进行实验的读者。理想情况下，读者应该能够轻松地更改示例以生成自己的解决方案。 |
| 任务 | 展示如何使用 Istio 功能实现单个目标。任务包含以步骤序列编写的过程。任务对功能的解释最少，但包含指向提供相关背景和知识的概念的链接。任务必须包含自动化测试，因为它们经过测试并为了技术准确性而维护。 | 想要使用 Istio 功能的读者。 |
| 设置页面 | 重点介绍完成 Istio 部署所需的安装步骤。设置页面必须包含自动化测试，因为它们经过测试并为了技术准确性而维护。 | 想要完成部署的新老 Istio 用户。 |
| 博文 | 重点介绍 Istio 或与其相关的产品和技术。博文分为以下三类
| 对项目有基本了解，想要以轶事、体验和更非正式的方式了解项目的读者。 |
| 新闻条目 | 重点介绍有关 Istio 和相关事件的及时信息。新闻条目通常会宣布新版本或即将举行的活动。 | 想要快速了解 Istio 社区的新动态和发生的事件的读者。 |
| 常见问题解答条目 | 提供常见问题的快速答案。答案不会介绍任何概念。而是提供实用建议或见解。答案必须链接到文档中的任务、概念或示例，以便读者了解更多信息。 | 有特定问题并希望获得简短答案和学习更多资源的读者。 |
| 操作指南 | 重点介绍在现实环境中运行 Istio 时遇到的特定问题的实用解决方案。 | 想要解决问题或实施运行 Istio 部署的解决方案的服务网格运营商。 |
选择标题
为你的主题选择一个包含你希望搜索引擎找到的关键词的标题。Istio 中的所有内容文件都命名为index.md，但每个内容文件都在一个文件夹中，该文件夹使用主题标题中的关键词，用连字符分隔，全部小写。使文件夹名称尽可能短，以便更容易创建和维护交叉引用。
将您的贡献提交到 GitHub
如果你不熟悉 GitHub，请参阅我们的使用 GitHub 指南，了解如何提交文档更改。
如果你想了解你的贡献是如何以及何时发布的，请参阅关于分支策略的部分，了解我们如何使用分支和 cherry-pick 来发布我们的内容。