Knative文档写作风格指南：技术文档的语言与表达规范

Knative文档写作风格指南：技术文档的语言与表达规范

docs User documentation for Knative components. 项目地址: https://gitcode.com/gh_mirrors/docs1/docs

前言

在编写Knative技术文档时，采用清晰、一致的语言风格至关重要。本文档将详细介绍Knative项目推荐的技术文档写作规范，帮助作者产出专业、易读的技术内容。

时态使用规范

技术文档应当使用现在时态，这能使内容更具即时性和确定性。

正确示例： "该命令启动一个网络服务。"

错误示例： "该命令将会启动一个网络服务。"

现在时态的表达更符合技术文档的特性，因为技术操作的效果通常是即时且确定的。

主动语态优先

主动语态能使句子更简洁有力，明确动作的执行者。

正确示例： "您可以使用浏览器探索API。" "YAML文件指定了副本数量。"

错误示例： "API可以通过浏览器被探索。" "副本数量在YAML文件中被指定。"

主动语态能减少被动结构带来的理解负担，特别对于非英语母语的读者更为友好。

简洁直接的表达方式

技术文档应当去除冗余词汇，直达要点。

正确示例： "要创建ReplicaSet，..." "查看配置文件。" "查看Pod。"

错误示例： "为了创建ReplicaSet，..." "请查看配置文件。" "通过下一个命令，我们将查看Pod。"

避免使用"please"等礼貌性词汇，技术文档应以信息传达效率为先。

读者称谓规范

文档应当直接以"你"来称呼读者，而非使用"我们"。

正确示例： "你可以通过...创建Deployment" "在前面的输出中，你可以看到..." "本页教你如何使用Pod。"

错误示例： "我们可以通过...创建Deployment" "在前面的输出中，我们可以看到..." "在本页中，我们将学习关于Pod的知识。"

直接使用"你"能增强文档的互动性和针对性，让读者感觉指导是专门为他/她而写。

避免专业术语和习惯用语

考虑到多语言读者的需求，应避免使用专业术语、习惯用语和拉丁语。

正确示例： "在内部，..." "创建一个新集群。" "初始情况下，..." "例如，..." "通过网关进入..."

错误示例： "在底层，..." "启动一个新集群。" "开箱即用，..." "e.g., ..." "经由网关进入..."

简单直白的语言能降低理解门槛，提高文档的普适性。

避免未来时表述

技术文档应专注于当前可实现的功能，避免对未来功能的承诺或暗示。如需说明开发中的特性，应添加明确的标识说明其状态。

避免时效性表述

避免使用"当前"、"新"等容易过时的表述。

正确示例： "在1.4版本中，..." "联邦特性提供..."

错误示例： "在当前版本中，..." "新的联邦特性提供..."

技术发展迅速，今天的"新"特性明天就可能成为标准功能，使用具体版本号更为准确。

避免主观难度描述

避免使用"只需"、"简单地"、"容易"等主观描述难度的词汇。

正确示例： "包含一个命令在..." "运行容器..." "你可以删除..." "这些步骤..."

错误示例： "仅需包含一个命令在..." "简单地运行容器..." "你可以轻松删除..." "这些简单的步骤..."

这些词汇不仅不能真正降低理解难度，还可能让遇到困难的读者产生挫败感。

结语

遵循这些写作规范，能够使Knative技术文档保持专业、一致且易于理解的特质。良好的文档是项目成功的重要组成部分，期待每位贡献者都能产出高质量的文档内容。

docs User documentation for Knative components. 项目地址: https://gitcode.com/gh_mirrors/docs1/docs