客观礼貌

客观礼貌#

技术文档应保持中立专业的叙述基调，具体要求如下：

语气规范#

  1. 信息客观性
    聚焦技术事实本身，避免产品推广话术
    × 不当示例："使用我们的SDK可以显著提升开发效率"
    √ 正确表述："该SDK提供标准化API接口，支持快速集成"

  2. 表达友好度
    采用冷静平和的指导语气，避免强硬措辞
    × 不当示例："你必须定期清理日志"
    √ 正确表述："建议建立日志定期清理机制"

语气规范#

  1. 修辞规范
    (1) 拟人化限制
    • 禁止赋予技术组件人类特征
    • 场景示例：
    × 不当（调试指南）："Redis缓存闹脾气不响应请求"
    √ 专业（监控文档）："Redis连接数超过maxclients限制"

    (2) 幽默元素管控
    • 原则上禁止技术文档使用幽默表达
    • 例外场景（需满足全部条件）：

    • 非核心内容（如示例代码注释）

    • 非关键业务流程说明

    • 示例：API文档的deprecated提示

句式规范#

  1. API文档特殊要求 • 参数说明避免推测性表述 × 不当："聪明的SDK会自动处理编码" √ 专业："SDK依据Content-Type头自动选择编码方案" • 错误码描述需保持技术中立 × 不当："服务端不高兴拒绝请求" √ 专业："服务端返回403 Forbidden状态码"

  2. 反问句禁用
    × 不当示例："难道这不是最佳实践吗？"
    √ 正确表述："该实践符合行业安全标准"

  3. 感叹句规范
    仅限高风险操作警示：

    ! 警告  
此操作将永久删除用户数据，请确认已做好备份！
目录