语言风格(文档)
人称及语态
【规则】使用第二人称。人称代词默认省略,必须出现时,推荐使用“开发者”而不是“你”。
正例 | 反例 |
使用IDE创建卡片工程。 | 我们使用IDE创建卡片工程。 |
【建议】尽量使用主动语态。即句子主语是执行动作的人或事物,而不是被操作的事物。
建议 | 不建议 |
配置参数A,声明支持B功能。 | A参数被配置后,即可支持B功能。 |
语气及用词
【规则】客观陈述内容,口吻友好。
正例 | 反例 |
确保配置正确。否则,会导致系统工作不正常。 | 你必须保证配置正确。否则后果自负。 |
【规则】避免使用口语化词语。
正例 | 反例 |
无 | “不准”、“……的话”、“就可以了”、“做……用”等。 |
【规则】避免行话。行话只有小部分人员能理解,且难以翻译。
【规则】避免成语和俗语。成语和俗语翻译时很难有效传达其确切含义,没有必要在技术资料中存在。
【规则】避免使用可能带有偏见或歧视含义的词汇,包括性别、种族、文化、年龄、技能、职业、宗教、经济水平等方面的偏见或歧视。
【规则】避免使用可能会引起操作者负面情绪的词语。
用户视角
【规则】为目标用户(指目标读者,本文简称用户)写作:
【规则】面向用户场景和用户任务写作:
文档内容应面向用户的真实场景和目标/任务,而非产品功能。
标题明确体现任务目标。
对于复杂任务流(超过5步),在操作开始前提供操作流程图或表。
提供清晰的、step-by-step的操作指导。适当配合界面截图使操作更直观,仅截取关键信息。
为用户任务就近提供操作支撑信息。
提供任务全流程所需的支撑信息,例如必要的背景信息、前提条件、准备动作、操作成功的验证方法、常见的故障处理和错误预防信息。
为所呈现的信息提供必要的理由(例如对用户理解或完成开发任务没有帮助的内部实现原理不需要提供)。
完整
【规则】避免任务场景缺失。开始写作前,应通过用户与任务分析活动,明确文档要提供哪些任务场景的指导信息。
【规则】通过写作模板来保证内容的完整性:
具体
【规则】用具体的描述代替抽象/晦涩的描述。
正例 | 反例 |
在编译构建过程中,提示LABEL_VALUE_ERROR错误信息。 | 编译构建失败。 |
【规则】表示数量或程度时,避免用笼统的“多”“少”“大”,改为具体的、易于感知或衡量的数字。
正例 | 反例 |
文件大于16MB | 文件超限 |
等待30分钟左右 | 等待较长的时间 |
CPU运行速度提升80% | 性能增强 |
简洁
【规则】使用主谓结构、主谓宾结构的句子,避免添加不必要的修饰成分。
【规则】避免使用长连句。同一句子中的逗号数不能超过5个。
【规则】禁止使用双重否定。
【规则】言简意赅,直接陈述观点。避免无意义的词语,包括表示程度、语气的词。
正例 | 反例 |
属性不允许重复定义。 | 每个属性最多只允许出现一次。 |
绑定服务与通知。 | 将服务与通知绑定就好了。 |
【规则】根据用户的技能水平,剔除不必要的信息。
清晰
【规则】确保语言描述清晰,不模糊,不晦涩,易理解(传递一个清楚的意思):
【规则】确保逻辑清晰:
一致
【规则】用词一致:术语、缩略语、描述同一对象的词汇要全文一致,符合用户的心理预期,禁止使用不同的词汇(包括中英文混用)描述同一事物或操作。
OpenHarmony常用词必须遵从下表。
正例 | 反例 |
登录 | 登陆 |
单击 | 点击 |
帐户 | 账户 |
帐号 | 账号 |
图像 | 图象 |
计费 | 记费 |
阈值 | 阀值 |
重写 | 复写 |
命令 | 指令 |
外形 | 外型 |
【规则】结构一致:相同文档或者同类信息,保持结构一致,有助于用户对文档结构的把握,方便信息的查找和理解。请优先在“OpenHarmony文档写作模板”中选择最贴近待写作内容的模板,遵循模板要求写作。
【规则】句式一致:使用一致的句式,不但使技术文档对外表现出一致的风格,也有助于用户在理解内容时,符合已经形成的思维惯性,理解起来更简单。例如统一使用祈使句描述动作。
【规则】格式一致:同类元素如代码块、文件路径等,格式保持一致,便于用户理解。
【建议】下表给出了另一部分常用词的推荐用法,请参考。
转载自:https://gitee.com/openharmony/docs/blob/master/zh-cn/contribute/style-guide/style-guide-language-style.md#