mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
locadex-agent[bot]
bced9bd6c4
Co-authored-by: locadex-agent[bot] <217277504+locadex-agent[bot]@users.noreply.github.com>
62 lines
2.6 KiB
Plaintext
62 lines
2.6 KiB
Plaintext
---
|
||
title: "风格与语气"
|
||
description: "以一致的风格撰写高效的技术文档。"
|
||
keywords: ["写作原则", "主动语态", "技术写作", "风格指南"]
|
||
---
|
||
|
||
<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> |