82 lines
3.9 KiB
Markdown
82 lines
3.9 KiB
Markdown
---
|
|
title: 语言风格
|
|
description: 本文强调技术文档写作应采用对话式、客观礼貌的语气，追求简洁明了、通俗易懂的表达，以用户为导向，并确保用词恰当、统一，正确使用“的”、“地”、“得”，明确代词指代，以提高文档的易用性和清晰度。
|
|
keywords:
|
|
- 技术文档
|
|
- 语言风格
|
|
- 简洁明了
|
|
- 通俗易懂
|
|
- 用户导向
|
|
tags:
|
|
- 技术/软件工程
|
|
- 软件工程/文档规范
|
|
author: 7Wate
|
|
date: 2024-08-07
|
|
---
|
|
|
|
在技术文档的写作中，风格和语气的掌握是至关重要的。下面是一些关于技术文档写作的基本准则。
|
|
|
|
## 对话式语气
|
|
|
|
技术文档的语言风格应该采用**平易近人、直截了当**的语气，比如使用「你可以…」这样的表达方式，避免过于正式或冗长的句子。
|
|
|
|
> 请使用下面的按钮来完成操作。❌
|
|
>
|
|
> 你可以使用下面的按钮来完成操作。
|
|
|
|
## 客观礼貌的语气
|
|
|
|
技术文档的语气应客观并保持礼貌，不进行产品推销，**主要目的是传达技术信息**。应该使用友好而有礼貌的措辞，避免强硬或粗鲁的语气。在指导性文档中，尽量保持语气冷静、客观且简洁。
|
|
|
|
> 你一定要按照这样做，否则会失败。❌
|
|
>
|
|
> 按照以下步骤操作，可以成功完成。
|
|
|
|
## 简洁清晰地表达
|
|
|
|
简洁明了是技术文档的重要原则。**建议作者在完成初稿后，通读整篇文档**，删去没有明显作用的字、词、句，将文档长度缩短，但同时确保信息传递效果不受影响。避免使用冗长的句子和逻辑混乱的段落，尽量使用主动语态，明确阐述主语和宾语。
|
|
|
|
> 如果在配置过程中出现问题，那么需要查看日志文件，然后分析日志文件中的错误信息，最后采取适当的措施来解决问题。❌
|
|
>
|
|
> 配置过程中出现问题时，查看日志文件，分析错误信息，并采取适当措施解决问题。
|
|
|
|
## 通俗易懂的语词
|
|
|
|
**使用通俗易懂的词语是技术文档的基本要求。**避免使用行话、俚语或网络流行语，或故意使用谐音错别字。应使用标准的技术术语，避免过度使用缩略语或专业术语，尽量用简单明了的表达方式。
|
|
|
|
> 这个软件有魔改功能，能让你的计算机跑得飞快！❌
|
|
>
|
|
> 这个软件有优化功能，可以提升计算机的运行速度。
|
|
|
|
## 以用户为导向
|
|
|
|
**技术文档应以用户为导向，从用户的角度思考问题，提供有用的信息。**在撰写文档时，考虑文档的目标读者可能的技术水平和实际操作中可能遇到的问题，尽可能全面且清晰地解释技术信息，并提供更多的详细信息和解决方案。建议进行文档可用性测试，让无技术背景的测试人员参照文档进行操作，以确保文档的易用性。
|
|
|
|
> 在设置菜单中，选择适当的选项以进行配置。❌
|
|
>
|
|
> 在设置菜单中，选择相关选项，以便进行配置。
|
|
|
|
## 用词恰当和统一
|
|
|
|
**在技术文档中，使用正确和一致的词汇非常重要。**你应避免使用可能引发冲突的词汇，并在同一篇或同一系列的技术文档中，保持一致的用词，避免造成混淆或阅读困难。
|
|
|
|
> 我们强烈推荐使用最新版本的软件。❌
|
|
>
|
|
> 建议使用最新版本的软件。
|
|
|
|
## 正确使用“的”、“地”、“得”
|
|
|
|
> 调度系统会将数据迁移到其他的存储节点上。（形容词＋的＋名词）
|
|
>
|
|
> 数据库可以显式地使用事务。（副词＋地＋动词）
|
|
>
|
|
> 这个值不宜调得过大。（动词＋得＋副词）
|
|
|
|
## 明确代词指代
|
|
|
|
你应确保代词的指代对象明确，避免造成读者的困惑。
|
|
|
|
> 如果希望从本地已编译好的二进制文件构建 PD、TiKV 或 TiDB 的镜像，需要将其 `image` 字段留空。❌
|
|
>
|
|
> 如果希望从本地已编译好的二进制文件构建 PD、TiKV 或 TiDB 的镜像，需要将相应镜像的 `image` 字段留空。
|