文档写作技巧

大部分人无法正确讲述一件事情，这非常反直觉，但这就是真相。

openai 出的"写文档的技巧"，从里面节选一部分，非常实用。

 

【提升表达清晰度】

 

语言优化要点

 

1. 简化句子结构、长句拆分为短句、减少副词使用、删除冗余词汇。

 

2. 消除理解障碍

 

避免歧义表述、减少名词堆砌、明确词性使用。

 

3. 保持指代清晰

 

避免跨句使用"这个""那个"，直接引用具体内容。

 

示例："基于消息格式化的讨论"优于"基于上一个话题"

 

4. 尊重读者自主性

 

避免预设读者状态（如"现在你可能想知道..."）

 

使用客观表述（如"要调用函数，请..."）

 

保持专业中立

 

【实现普惠性文档】

 

包容性设计原则

 

1. 简化表达层次

 

解释要比"必要程度"更充分、考虑非母语读者需求、平衡专业性与通俗性。

 

2. 规范术语使用

 

避免缩写、明确专业术语（使用"输入"而非"提示词"）、选择具体表述（"最大词元限制"优于"上下文限制"）

 

3. 完善支持信息

 

主动提供基础操作指导、考虑跨领域专家的知识盲区、宁可过度解释，也不遗漏关键步骤。

 

4. 合理设置优先级

 

常见问题文档优先于特殊场景、基于实际价值安排内容权重。

 

5. 设计友好导言

 

使用宽泛开场引入专业主题、建立已知与未知的连接、降低读者进入陌生领域的心理门槛。