gutenbergdocs/docs/contributors/documentation/copy-guide.md

# 文案撰写指南

## 长文本规范

适用于编写多行/多步骤说明，或对页面功能进行叙述性引导的规范。

具体内容会随语境变化，但以下通用建议可供参考：

#### 第一：善用缩写形式！

缩写更符合对话习惯，能轻松让文本显得亲切自然（同时还能节省篇幅：可谓双赢）。

#### 第二：删减冗余表达

以下两种情形常出现堆砌词藻却不表意的情况：

首先是使用被动语态时：
> 该区块可用于展示单张图片。

当看到“可用于”“被用于”等表述时需警惕：你正在使用被动语态。改用主动语态能让句子更简洁有力：
> 该区块展示单张图片。

其次是回避明确断言而使用模糊表述时：
> 图库区块可帮助您以优雅布局展示多张图片。

到底能不能？既然是我们开发的软件，就应该明确说明其功能：
> 图库区块以优雅布局展示多张图片。

“允许您”这个短语也常被滥用：
> 预格式化文本允许您保留制表符和换行符。

功能本身并不“允许”用户操作，它们只是实现特定目标的工具。直接说明其作用即可：
> 预格式化文本会保留制表符和换行符。

更直接的表述往往更清晰。建议在审校时重点检查“可以”“能够”“可能”“允许您”“帮助”等高频冗余词，这些都是需要精简表述的常见信号。

#### 第三：慎用“简单”“便捷”“只需”

我们无权定义何为简单——这应由用户判定。若宣称某项操作简单，而用户实际体验却并非如此，会削弱用户对我们及产品的信任。“只需”同样如此——许多人知道避免使用“简单”，却频繁使用“只需”。“只需点击这里”“只需输入用户名”，这种表述暗示操作轻而易举，但我们无法预知用户可能遇到的困难。

具体说明往往更安全有效。“简单”和“便捷”常是我们未充分解释的托辞。遇到这些词时，请思考它们替代的具体含义。例如“按回车键添加区块很简单”实际想表达的是“您无需将手离开键盘即可为页面添加内容”。既然如此，何不直接说明具体优势？

当然并非要完全禁用这些词汇。当描述封面图区块需要更少配置，或介绍快速创建自定义区块工具时，完全可以说“封面图区块已简化”或“我们正让自定义区块创建更便捷”——此时这些词是相对且描述性的。重点是要避免将其用作绝对断言，并借机提供更具体明确的说明。

#### 第四：警惕“我们”滥用

当文本频繁出现“我们”，意味着焦点偏离了软件使用者而转向开发者。虽然有时确需如此，但多数情况下，重点应始终围绕用户需求及其获得的价值，而非“我们的成果”或“我们的意图”。

只有我们自己在意这些；用户要的只是好用的软件。若发现文本中“我们”频现，请考虑将表述重构为聚焦用户获益与成功体验。

#### 五、注意字母大小写规范

标题和副标题有两种书写格式：

**标题格式**：每个单词的首字母大写  
**句子格式**：仅句首单词首字母大写

功能名称和仪表板区域通常采用标题格式（如"站点统计"或"最新发布"），而功能标签则多使用句子格式（如"显示按钮"或"评论点赞功能"——其中"点赞"因作为功能名称需首字母大写，但整体标签仍遵循句子格式）。

当处理整页界面文本时，请确保同类文本（标题、工具提示、按钮等）保持统一的大小写规范。

## 错误信息撰写指南

如何编写清晰实用的错误信息

#### 一、重视错误信息中的语气与语调——它们传递着重要信息

语气语调传递的信息量不亚于文字本身。错误信息需要承载大量信息且通常要求简洁，但切忌牺牲语调的平衡，避免走向负面苛责或过度乐观的极端。

假设用户因权限不足无法发布文章，以下是我们应避免的表述方式：

> 您的用户角色不正确。

这种表述显得疏离冷漠。

> 停！您无权进行此操作。

这种表述带有不必要的警告意味和严厉感。

> 哎呀，我们不能让您这么操作哦！

这种表述显得过于轻佻。

即便在错误提示中，我们仍可保持直接、积极且友善的沟通。具体如何实现？请看第二至第四条建议！

#### 二、尽可能提供解决方案

优秀的错误信息不应仅停留在问题告知：

> 您的用户角色不正确。

然后呢？为什么这很重要？我该如何解决？这条信息对我有何帮助？用户需要了解角色权限的重要性，以及如何获取相应权限来完成目标操作。若错误信息未提供指导，用户将陷入困境——如果我们不明确说明，用户很可能重复触发相同的错误。

#### 三、避免为节省空间而滥用专业术语

> 您的用户角色不正确。请联系站点管理员。

这个版本似乎有所改进：至少指明了解决方向。

但细想仍存缺陷：用户仍不清楚自身角色定位及其重要性，也不明白"站点管理员"具体指代谁、如何联系。

虽然这条错误信息在技术上完全准确，但并未传递有效信息。若以理解和解决问题为目标，技术准确性未必能直接达成。

"您的账号暂无文章发布权限"虽未采用用户角色界面的专业术语，但清晰说明了问题症结，即使用户不了解"用户角色"概念也能理解。基于这种认知，即使提示信息止步于此，用户也能意识到需要申请权限。

与现有界面术语保持一致固然重要，但绝不能以牺牲理解为代价。

#### 四、切勿假定用户理解错误来源

> 您的用户角色不正确。

在我们看来，用户显然是在尝试发布内容或修改无权限设置时触发此提示。但对用户而言未必如此：用户往往会频繁点击操作，特别是在不确定如何完成某项任务时，未必能立即记起前序操作页面或设置项（及其意图）。

优秀的错误信息应包含引导用户的上下文提示。"您的账号暂无文章发布权限"既提醒了用户尝试发布文章的操作意图，也明确了触发错误的具体障碍所在。

## 项目符号列表

（顾名思义）撰写项目符号列表的指南

#### 第一：保持所有条目句式结构平行

平行结构能让列表更便于快速阅读——其可预测性能减轻读者的认知负担。

**优秀范例：**
> 这个区块能实现什么功能？应有尽有！
>
> -   添加引用内容
> -   高亮心仪链接
> -   展示多张图片
> -   创建项目符号列表

每个条目都是完整句子并以句号结尾（若列表均为单字或双字条目，通常可合并为常规单句——既提升可读性又节省空间）。每行皆以动词开头说明区块功能，且主语始终指向用户。用户能快速理解此列表，因为读完首条后即可掌握后续内容的阅读逻辑与信息类型。

**欠佳示例：**
> 这个区块能实现什么功能？应有尽有！
>
> -   您可以添加引用内容
> -   高亮您喜欢的链接
> -   它能展示多张图片，很适合创建相册！
> -   项目符号列表

本例中各行表述方式各异（有的以动词开头，有的以名词开头），句子主语不断切换（时而用户，时而区块），部分条目附加说明而部分没有，存在不完整句子且标点使用不统一。阅读此类列表需要耗费更多精力，因为读者必须逐条解析内容，无法预判各条目信息结构。

注意：这并非要求每个条目都必须简短且以行为动词开头！“可预测”不等于“简单化”，核心在于保持一致的句式结构。以下示例同样符合规范：
> 这个区块能实现什么功能？应有尽有！
>
> -   尝试添加引用——有时他人的表述更为精妙！
> -   用它高亮心仪链接，链接分享可是互联网的硬通货
> -   创建展示多图的美术馆，尽情呈现您的摄影佳作

本例中各条目以更具用户视角的动词开头，并辅以补充信息增强趣味性。标点符号的灵活运用避免了刻板感，但由于基本结构一致，仍保持良好可读性。

#### 第二：犹豫不决时，以动词启句（但无需固守同一动词）

必须使用动词开头吗？非也。但若举棋不定，选择动词开头通常稳妥（尤其当列表描述系列动作或可选操作时）。在纯粹的操作说明中（如需要用户做出选择的界面文案），所有条目使用相同动词开头并无不可：

> 请选择后续操作：
>
> -   添加纯文本区块
> -   添加引文区块
> -   添加图片区块

若列表更具说服性质（如通过列举优势引导功能使用）或包含多步骤说明，则应变换动词以生动语言吸引读者：

> 这个区块能实现什么功能？应有尽有！
>
> -   尝试添加引用——有时他人的表述更为精妙！
> -   用它高亮心仪链接，链接分享可是互联网的硬通货
> -   创建展示多图的美术馆，尽情呈现您的摄影佳作

这些并非铁律——例如在说服性列表中，为增强聚焦性与冲击力亦可使用相同动词。但上述原则确是构建优质列表的基石。

#### 第三：当内容明显是列表时，无需刻意声明

**优秀范例：**
> 这个区块能实现什么功能？应有尽有！
>
> -   添加引用内容
> -   高亮心仪链接
> -   展示多张图片

**欠佳示例：**
> 这个区块能实现什么功能？应有尽有！以下是部分使用场景示例：
>
> -   您可以添加引用内容
> -   高亮您喜欢的链接
> -   它能展示多张图片，很适合创建相册！

要在极致清晰与信任用户之间找到平衡。一方面我们深知用户未必细读说明，另一方面冗余提示又易让用户产生被低估智商的感受。

#### 四、善用粗体突出重点

在项目符号列表中，粗体能引导读者关注核心信息。当列表项包含补充性次要内容时，这种方法尤为有效。

“关键信息”是精髓所在：粗体自带视觉引力，因此请始终聚焦每个列表项中最核心的内容：

> 这个区块有哪些功能？应有尽有！
>
> -   尝试插入**引述**——有时他人的精辟见解最值得分享
> -   用它高亮你钟爱的**链接**——分享链接是互联网的硬通货
> -   创建展示多张图片的**相册**，尽情呈现你的摄影佳作

反之，过度使用粗体会造成视觉混乱：

> **这个区块有哪些功能？** 应有尽有！
>
> -   尝试插入**引述**——有时他人的精辟见解最值得分享
> -   用它高亮你钟爱的**链接**——分享**链接**是互联网的硬通货
> -   创建展示**多张图片**的**相册**，尽情呈现你的最佳**摄影作品**

当列表简短基础时，无需使用粗体——徒增冗余：

> 这个区块有哪些功能？应有尽有！
>
> -   插入**引述**
> -   高亮**链接**
> -   展示多张**图片**

简洁的表述自带聚焦效果，无需额外强调。

## 界面描述指南

撰写功能简介或选项说明的单行文本规范

#### 一、清晰至上！

若用户无法理解选择某项功能将实现什么效果，再巧妙的双关语也毫无意义。文字游戏和俚语往往表意模糊，容易引发误解。如确需使用，应仅作为补充信息——绝不可用于解释核心功能——且必须确保能被广泛理解。

#### 二、呼应首章原则，警惕冗余表达

主动语态通常更优，在有限的界面空间里，精简表达对用户快速决策至关重要。以下对比可见如何通过精简实现更清晰的指引：

> 当您点击X时，将会触发Y效果

对比

> 点击X即可实现Y

虽然补充说明看似能引导用户，实则模糊了核心信息：

> 当您点击“设置”按钮时，弹窗将显示所有可用的高级设置

对比

> 点击“设置”访问高级选项

类似冗余表达还有“当您完成X后…”或“若需实现X…”。虽然在用户需要决策路径时后者确有必要，但多数情况下，“要实现X…”的简洁表达更为高效。

#### 三、明确具体

当操作需要前置条件时，必须明确说明具体要求及后续效果。避免使用“当您准备就绪时”这类模糊表述——准备什么？需具体说明前提条件。

“准备就绪”可能指：
-   当需要添加新内容区块时
-   当对文章内容满意时
-   完成文章校对后
-   当需要设置特色图片时
-   完成所有参数配置后

包罗万象的表述实则毫无意义。指引越具体，实用性越强，用户对产品的信任度也越高。

#### 四、保留文字温度

虽以清晰为首要原则，且界面空间有限，但说明文字仍可保有感染力。

单行描述也应保持完整句式：
> 列表。支持编号与符号形式

对比

> 添加列表，可选择编号或符号样式

适当使用缩略形式：
> 添加列表。系统将提供格式选项

对比

> 添加符号列表——我们会提供格式选项

善用标点构建语言节奏：
> 列表。支持编号与符号形式

对比

> 添加列表——编号或符号样式任君选择

坚持使用通俗表达：
> 添加无序列表或有序列表

对比

> 添加列表，可选择编号或符号样式

（再次强调：请勿使用文字游戏！“感染力”在界面指引中应是含蓄的——我们要的是自然的人性化表达，而非刻意的俏皮话。）