istio
/
istio.io
mirror of https://github.com/istio/istio.io.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
istio.io/content/zh/docs/releases/contribute/add-content/index.md

7.1 KiB
Raw Permalink Blame History

title description weight aliases keywords
添加新文档 介绍如何为 Istio 贡献新文档。 3
/zh/docs/welcome/contribute/writing-a-new-topic.html
/zh/docs/reference/contribute/writing-a-new-topic.html
/zh/about/contribute/writing-a-new-topic.html
/zh/create
contribute

贡献新文档到 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 来发布我们的内容。