> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.another-horizon.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# 风格与语气

> 以一致的风格撰写高效的技术文档。

<Tip>
  本页介绍撰写技术文档的风格取舍、常见误区与实现建议。
</Tip>

<div id="writing-principles">
  ## 写作原则
</div>

* **保持简洁。** 人们阅读文档是为达成目标。尽快切入要点。
* **清晰优先于巧妙。** 表达要简单直接，避免术语或复杂句式。
* **使用主动语态。** 与其说“应创建一个配置文件”，不如说“创建一个配置文件。”
* **便于浏览。** 用标题帮助读者定位，拆分长段落，使用项目符号和列表以便快速扫读。
* **使用第二人称写作。** 直接指向读者更便于他们按步骤操作，也让文档更具亲和力。

<div id="common-writing-mistakes">
  ## 常见写作错误
</div>

* **拼写和语法错误。** 即便只有少量拼写和语法错误，也会削弱文档的可信度，并降低可读性。
* **术语不一致。** 在一段中将某个概念称为 “API key”，下一段又叫它 “API token”，会让用户难以理解和跟上内容。
* **过于以产品为中心的术语。** 你的用户并不具备对你产品的完整上下文。应使用用户更熟悉的语言。
* **口语化表达。** 尤其在本地化场景下，口语化表达会降低内容的清晰度。

<div id="tips-for-enforcing-style">
  ## 执行风格的实用建议
</div>

利用现有风格指南来规范你的文档：

* [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/)
* [Splunk Style Guide](https://docs.splunk.com/Documentation/StyleGuide/current/StyleGuide/Howtouse)
* [Google Developer Documentation Style Guide](https://developers.google.com/style)

当你明确要采纳哪些写作原则后，尽可能将其自动化。你可以使用 [CI checks](/zh/deploy/ci) 或像 [Vale](https://vale.sh) 这样的 linter。

<div id="related-pages">
  ## 相关页面
</div>

<CardGroup cols={2}>
  <Card title="内容类型" icon="folder-tree" href="/zh/guides/content-types">
    根据文档目标选择合适的内容类型。
  </Card>

  <Card title="无障碍性" icon="person-standing" href="/zh/guides/accessibility">
    让更多用户无障碍地访问你的文档。
  </Card>

  <Card title="格式化文本" icon="case-sensitive" href="/zh/create/text">
    了解文本格式和样式选项。
  </Card>

  <Card title="SEO（搜索引擎优化）最佳实践" icon="search" href="/zh/guides/seo">
    提升文档的可发现性。
  </Card>
</CardGroup>