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