---
title: 添加新文档
description: 介绍如何为 Istio 贡献新文档。
weight: 3
aliases:
    - /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
keywords: [contribute]
---

贡献新文档到 Istio，请执行以下步骤：

1. 确定受众和信息的预期用途。
1. 选择您想要贡献的[内容类型](#content-types)。
1. [命名标题](#choosing-a-title)。
1. 按照[文档贡献指南](/zh/about/contribute)撰写您的贡献。
1. 将您的贡献提交到 [GitHub 存储库](https://github.com/istio/istio.io)。
1. 执行[审核流程](/zh/about/contribute/review)，直到您的贡献被合并。

## 确定受众和信息的预期用途   {#identify-the-audience-and-intended-use}

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

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

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

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

- 读者是运维人员，而不是软件工程师（SWE）：提供执行脚本，而不是开发人员指南中的代码示例链接。

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

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

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

如果您需要帮助特定内容的受众，我们很乐意在
[文档工作组](https://github.com/istio/community/blob/master/WORKING-GROUPS.md#istio-working-groups)
每两周一次的会议上帮助您并回答您的所有问题。

## 内容类型  {#content-types}

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

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

## 命名标题  {#choosing-a-title}

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

## 将您的贡献提交到 GitHub  {#submit-your-contribution-to-GitHub}

如果您不熟悉 GitHub，请参阅[使用 GitHub 参与社区活动](/zh/about/contribute/github)，以了解如何提交文档更改。

如果您想了解有关发表文稿的方式和时间的更多信息，请参阅[分支策略](/zh/about/contribute/github#branching-strategy)，
以了解我们如何使用分支和 `cherry picking` 来发布我们的内容。