wiki/Technology/SoftwareEngineering/文档规范/4.语言风格.md

---
title: 语言风格
description: 本文强调技术文档写作应采用对话式、客观礼貌的语气，追求简洁明了、通俗易懂的表达，以用户为导向，并确保用词恰当、统一，正确使用“的”、“地”、“得”，明确代词指代，以提高文档的易用性和清晰度。
keywords:
  - 技术文档
  - 语言风格
  - 简洁明了
  - 通俗易懂
  - 用户导向
tags:
  - 技术/软件工程
  - 软件工程/文档规范
author: 7Wate
date: 2024-08-07
---

在技术文档的写作中，风格和语气的掌握是至关重要的。下面是一些关于技术文档写作的基本准则。

## 对话式语气

技术文档的语言风格应该采用**平易近人、直截了当**的语气，比如使用「你可以…」这样的表达方式，避免过于正式或冗长的句子。

> 请使用下面的按钮来完成操作。❌
>
> 你可以使用下面的按钮来完成操作。

## 客观礼貌的语气

技术文档的语气应客观并保持礼貌，不进行产品推销，**主要目的是传达技术信息**。应该使用友好而有礼貌的措辞，避免强硬或粗鲁的语气。在指导性文档中，尽量保持语气冷静、客观且简洁。

> 你一定要按照这样做，否则会失败。❌
>
> 按照以下步骤操作，可以成功完成。

## 简洁清晰地表达

简洁明了是技术文档的重要原则。**建议作者在完成初稿后，通读整篇文档**，删去没有明显作用的字、词、句，将文档长度缩短，但同时确保信息传递效果不受影响。避免使用冗长的句子和逻辑混乱的段落，尽量使用主动语态，明确阐述主语和宾语。

> 如果在配置过程中出现问题，那么需要查看日志文件，然后分析日志文件中的错误信息，最后采取适当的措施来解决问题。❌
>
> 配置过程中出现问题时，查看日志文件，分析错误信息，并采取适当措施解决问题。

## 通俗易懂的语词

**使用通俗易懂的词语是技术文档的基本要求。**避免使用行话、俚语或网络流行语，或故意使用谐音错别字。应使用标准的技术术语，避免过度使用缩略语或专业术语，尽量用简单明了的表达方式。

> 这个软件有魔改功能，能让你的计算机跑得飞快！❌
>
> 这个软件有优化功能，可以提升计算机的运行速度。

## 以用户为导向

**技术文档应以用户为导向，从用户的角度思考问题，提供有用的信息。**在撰写文档时，考虑文档的目标读者可能的技术水平和实际操作中可能遇到的问题，尽可能全面且清晰地解释技术信息，并提供更多的详细信息和解决方案。建议进行文档可用性测试，让无技术背景的测试人员参照文档进行操作，以确保文档的易用性。

> 在设置菜单中，选择适当的选项以进行配置。❌
>
> 在设置菜单中，选择相关选项，以便进行配置。

## 用词恰当和统一

**在技术文档中，使用正确和一致的词汇非常重要。**你应避免使用可能引发冲突的词汇，并在同一篇或同一系列的技术文档中，保持一致的用词，避免造成混淆或阅读困难。

> 我们强烈推荐使用最新版本的软件。❌
>
> 建议使用最新版本的软件。

## 正确使用“的”、“地”、“得”

> 调度系统会将数据迁移到其他的存储节点上。（形容词＋的＋名词）
>
> 数据库可以显式地使用事务。（副词＋地＋动词）
>
> 这个值不宜调得过大。（动词＋得＋副词）

## 明确代词指代

你应确保代词的指代对象明确，避免造成读者的困惑。

> 如果希望从本地已编译好的二进制文件构建 PD、TiKV 或 TiDB 的镜像，需要将其 `image` 字段留空。❌
>
> 如果希望从本地已编译好的二进制文件构建 PD、TiKV 或 TiDB 的镜像，需要将相应镜像的 `image` 字段留空。