技术写作指南：核心原则和最佳实践

下文是一份专为中级技术写作者设计的关于撰写产品手册的全面技术写作指南。目标在于帮助您提升技术文档质量和可用性，满足对技术部分熟悉的目标读者的需求。

📝 核心原则

• 原则：明确性优先
  描述：使用清晰、具体的语言表达概念，避免歧义，让读者快速理解核心信息，而无需反复揣摩含义。
  优先级：5

• 原则：目标导向
  描述：以用户需要能够完成的任务为导向撰写文档，而非仅仅介绍技术功能，让文档真正解决问题。
  优先级：5

• 原则：简洁性
  描述：去除冗长繁杂的内容，只写必要信息。使用简短、精炼的句子，以减少信息过载。
  优先级：4

• 原则：一致性
  描述：确保语言、术语和格式的一致性。这让读者无需适应变化的表达方式，从而专注于信息本身。
  优先级：4

• 原则：结构化信息
  描述：将文档内容分解为合理的小块（如章节、步骤、提示等），使用逻辑顺序呈现，让读者快速找到需要的信息。
  优先级：4

✍️ 写作风格指南

• 指南：使用主动语态
  示例：

  • ✅ “单击‘保存’按钮以完成配置。”
  • ❌ “‘保存’按钮可以被单击以完成配置。”
    注意事项：优先使用主动句式，能清晰传达谁需要执行操作。

• 指南：避免行话和不必要的技术术语
  示例：

  • ✅ “重启系统以应用更改。”
  • ❌ “触发系统内核进程重新加载以应用持久更改。”
    注意事项：除非必要，否则避免使用读者可能不熟悉的术语，并在首次提及时明确解释。

• 指南：分步骤操作时，明确顺序描述
  示例：

  • ✅
    1. 单击“设置”。
    2. 选择“高级选项”。
    3. 启用“高效模式”。
  • ❌ “设置页面有很多选项，选择你需要启用的部分。”
    注意事项：步骤必须短小、明确，确保每一步操作具有唯一性。

• 指南：使用图表和代码片段支持说明
  示例：

  示例代码：
  print("Hello, World!")
  

  注意事项：在适当场景补充图片、代码或表格，用直观方式帮助读者理解。

• 指南：保持读者视角
  示例：

  • ✅ “在第一步，确保设备已连接电源。”
  • ❌ “在第一步，该设备需要有一个未断开的电源。”
    注意事项：面向读者提需求，用简明表达直接代入情境。

🔧 文档结构

🎯 质量检查清单

✅ 应包含：

• 明确的文档目标和适用读者范围。
• 逻辑清晰、易导航的结构（如目录清单和标题层级）。
• 简洁的标题和小节分块，方便用户快速定位。
• 使用编号列表和项目符号列出操作步骤。
• 支持文字说明的截图、图标或代码示例。
• 明确定义的术语表或首次出现术语的解释。
• 支持不同熟悉度用户的说明深度，基础与进阶内容分开。
• 语法、拼写和标点无误。

❌ 应避免：

• 长句堆砌导致信息模糊。
• 不必要的技术术语或缩写，特别是未定义的术语。
• 大段未分段的文字，缺乏视觉层次。
• 格式不一致，例如标题大小或字体变化。
• 默认用户已熟悉每个功能或上下文，未作说明。
• 表述内容主观或使用含糊语气，如“可能会”、“很多”。
• 忽略质量保证审核流程中的用户反馈。

通过遵循以上核心原则和最佳实践，您可以在撰写产品手册时创建清晰、易用且符合目标读者需求的技术文档！

以下是关于有效技术写作（特别是针对API文档）的有效指南。此指南将聚焦于对技术文档质量和可用性影响最大的核心原则和最佳实践，并顺应高级技术写作需求。

📝 核心原则

• 原则：清晰性优先 描述：确保每个句子、段落和内容模块都易于理解。优先选择简单、明确的语言，避免模棱两可或复杂的表达。 优先级：5

• 原则：目标导向 描述：始终聚焦目标读者的需求，确保文档的核心内容解决实际问题或回答读者最迫切的问题。 优先级：5

• 原则：一致性 描述：采用一致的术语、格式和语法规则，以减少认知负担。确保API端点说明、代码示例以及返回值格式具有高度统一性。 优先级：4

• 原则：模块化 描述：将文档拆分为小而独立的模块或章节，便于快速查找和复用。每个模块应只处理一个主题。 优先级：4

• 原则：以示例驱动 描述：通过实际的代码示例和用例展示API的使用方式，并确保示例贴近现实且功能完备。 优先级：5

✍️ 写作风格指南

• 指南：使用主动语态和直接语言 示例：

  • 推荐：“使用此API端点从数据库中检索数据。”
  • 避免：“数据可以通过此API端点从数据库中被检索。”
    注意事项：主动语态有助于凸显动作主体，避免句意模糊。

• 指南：避免行话或不必要的复杂术语 示例：

  • 推荐：“请输入有效的JSON格式。”
  • 避免：“遵循序列化和数据格式化规范。”
    注意事项：保留读者熟悉的专业术语，但不要过度堆砌。

• 指南：使用语法平行结构 示例：

  • 推荐：“检索数据、设置参数、返回响应。”
  • 避免：“数据可以被检索，设置参数，然后响应返回。”
    注意事项：保持列表句式一致，增强流畅性。

• 指南：保持代码示例格式清晰 示例：

  {
      "status": "success",
      "data": {
          "id": 123,
          "name": "John Doe"
      }
  }
  

  注意事项：使用代码格式化工具，确保缩进和标点符合通用实践。

• 指南：避免假设用户背景知识 示例：

  • 推荐：“此API端点支持GET请求，用于检索用户数据。”
  • 避免：“只需运行GET请求就行了。”
    注意事项：即使目标读者是专家，也不可忽视基本背景或操作环境的描述。

🔧 文档结构

🎯 质量检查清单

✅ 应包含：

• 文档顶部的版本号及最后更新时间。
• 功能完备、可运行的代码示例。
• 每个端点清楚标记方法类型（GET/POST等）及路径。
• 输入参数、请求/响应示例及格式说明。
• 错误代码及对应的解决方案。
• 高级用例或复杂操作的分步指南。
• 清晰的术语表解释关键技术术语。
• 配置步骤确保常见环境可以成功运行。

❌ 应避免：

• 不完整或错误的代码示例，如遗漏必要参数的示例。
• 专业术语堆砌但缺乏实际意义的描述。
• 过长或复杂的句子，导致难以理解。
• 假设目标读者“已经知道”全部背景信息。
• 不一致的术语或格式，例如同一术语在文档中的不同写法。
• 过时的内容或未更新的端点说明。
• 缺乏内容层级结构的文档布局。

通过遵循这份综合技术写作指南，您可以高效创建优质的API文档，确保满足高级读者的技术需求，并提供最佳用户体验。