docs
This commit is contained in:
213
docs/contributors/documentation/README.md
Normal file
213
docs/contributors/documentation/README.md
Normal file
@@ -0,0 +1,213 @@
|
||||
### 提示说明
|
||||
|
||||
区块编辑器手册支持与其他WordPress手册相同的[提示样式](https://make.wordpress.org/docs/handbook/documentation-team-handbook/handbooks-style-and-formatting-guide/#formatting)。但由于区块编辑器手册文档发布位置（npm、GitHub）不同，短代码的实现方式并不理想。
|
||||
|
||||
推荐的Markdown实现方式是使用原始HTML和`callout callout-LEVEL`类。例如：
|
||||
|
||||
```html
|
||||
<div class="callout callout-info">这是一个**信息**提示框。</div>
|
||||
```
|
||||
|
||||
可用的样式类包括：`info`、`tip`、`alert`、`warning`
|
||||
|
||||
<div class="callout callout-tip">
|
||||
这是一个**技巧**提示框。
|
||||
</div>
|
||||
|
||||
<div class="callout callout-info">
|
||||
这是一个**信息**提示框。
|
||||
</div>
|
||||
|
||||
<div class="callout callout-alert">
|
||||
这是一个**警示**提示框。
|
||||
</div>
|
||||
|
||||
<div class="callout callout-warning">
|
||||
这是一个**警告**提示框。
|
||||
</div>
|
||||
|
||||
<div class="callout callout-warning">
|
||||
注意：在提示框中，链接也需要使用HTML `<a href></a>`标签表示法。
|
||||
常规的链接转换不适用于提示框中的链接。
|
||||
例如，要访问"入门指南 > 创建区块"页面，GitHub中的URL是
|
||||
https://developer.wordpress.org/docs/getting-started/devenv/get-started-with-create-block.md
|
||||
但在区块编辑器手册中需要硬编码为
|
||||
<a href="https://developer.wordpress.org/block-editor/getting-started/create-block/">https://developer.wordpress.org/block-editor/getting-started/create-block/</a> 才能正确链接。
|
||||
</div>
|
||||
|
||||
### 编辑器配置
|
||||
|
||||
您应该配置编辑器使用Prettier自动格式化Markdown文档。完整详情请参阅[入门文档](/docs/contributors/code/getting-started-with-code-contribution.md)。
|
||||
|
||||
使用Visual Studio Code和Prettier扩展的配置示例：
|
||||
|
||||
```json
|
||||
"[[markdown]]": {
|
||||
"editor.defaultFormatter": "esbenp.prettier-vscode",
|
||||
"editor.formatOnSave": true
|
||||
},
|
||||
```
|
||||
|
||||
<div class="callout callout-info">
|
||||
根据您查看本文档的位置，方括号可能显示为双括号。正确格式应为单层方括号。
|
||||
</div>
|
||||
|
||||
### 视频嵌入
|
||||
|
||||
区块编辑器手册中的视频需要以未公开形式托管在[WordPress YouTube频道](https://www.youtube.com/@WordPress)。此过程需要额外权限。如需帮助，请在Slack的#marketing频道中联系。
|
||||
|
||||
视频上传到YouTube后，获取视频嵌入链接。链接格式如下：
|
||||
|
||||
```
|
||||
https://www.youtube.com/embed/nrut8SfXA44?si=YxvmHmAoYx-BDCog
|
||||
```
|
||||
|
||||
然后，在文档中需要嵌入视频的位置放置以下代码。请相应更新嵌入链接和视频标题。
|
||||
|
||||
```html
|
||||
<iframe width="960" height="540" src="[视频嵌入链接]" title="[视频标题]" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen="true"></iframe>
|
||||
```
|
||||
|
||||
<div class="callout callout-info">
|
||||
视频应采用<code>16:9</code>宽高比，并以最高分辨率拍摄。
|
||||
</div>
|
||||
|
||||
## 资源
|
||||
|
||||
- [文案指南](/docs/contributors/documentation/copy-guide.md) - 为Gutenberg项目编写说明、文档或其他贡献的指南
|
||||
|
||||
- WordPress文档团队的[语气与风格指南](https://make.wordpress.org/docs/handbook/documentation-team-handbook/tone-and-voice-guide/)
|
||||
|
||||
# 文档贡献指南
|
||||
|
||||
关于如何开始为古腾堡项目贡献文档的指南。
|
||||
|
||||
## 讨论渠道
|
||||
|
||||
[WordPress文档制作博客](https://make.wordpress.org/docs/)是获取WordPress文档最新信息的主要平台，包括公告、产品目标、会议记录、会议议程等。
|
||||
|
||||
文档相关的实时讨论在[WordPress官方Slack](https://make.wordpress.org/chat)的`#docs`频道进行（需要注册）。文档团队的每周例会于UTC时间每周二14:00举行。
|
||||
|
||||
古腾堡项目使用GitHub管理代码和跟踪问题。主代码库位于：[https://github.com/WordPress/gutenberg](https://github.com/WordPress/gutenberg)。如需查找可处理的文档问题，请浏览[带有文档标签的议题](https://github.com/WordPress/gutenberg/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3A%22%5BType%5D+Documentation%22+)。
|
||||
|
||||
## 文档类型
|
||||
|
||||
古腾堡项目包含两大类文档：
|
||||
|
||||
1. [用户文档](https://wordpress.org/documentation/article/wordpress-block-editor/)：介绍作者如何使用编辑器发布文章。要贡献用户文档，请关注文档博客或通过#docs Slack频道了解当前优先事项。
|
||||
2. [区块编辑器手册](https://developer.wordpress.org/block-editor/)：涵盖与古腾堡项目相关的所有内容，包括开发、扩展以及您正在阅读的专门针对古腾堡的贡献指南。
|
||||
|
||||
本文档剩余部分将重点说明如何贡献区块编辑器手册。
|
||||
|
||||
## 区块编辑器手册流程
|
||||
|
||||
区块编辑器手册由[古腾堡项目代码库](https://github.com/WordPress/gutenberg/)中`/docs/`目录的Markdown文件与软件包生成的文档共同组成。
|
||||
|
||||
自动化任务会每隔15分钟将文档发布至[区块编辑器手册站点](https://developer.wordpress.org/block-editor/)。
|
||||
|
||||
关于如何使用git通过拉取请求部署更改，请参阅[Git工作流程](/docs/contributors/code/git-workflow.md)文档。另可观看[视频教程](https://wordpress.tv/2020/09/02/marcus-kazmierczak-contribute-developer-documentation-to-gutenberg/)及配套的[古腾堡文档贡献幻灯片](https://mkaz.blog/wordpress/contribute-developer-documentation-to-gutenberg/)。
|
||||
|
||||
### 手册结构
|
||||
|
||||
手册根据文档功能类型划分为四个部分。[文档系统](https://documentation.divio.com/)详细阐述了各类文档的需求和功能，简而言之包括：
|
||||
|
||||
- **入门教程** - 引导学习者逐步完成目标的完整课程，例如[创建区块教程](/docs/getting-started/devenv/get-started-with-create-block.md)。
|
||||
- **操作指南** - 针对完成特定小型任务的简短教程，例如[如何向区块工具栏添加按钮](/docs/how-to-guides/format-api.md)。
|
||||
- **参考指南** - API文档，纯功能说明。
|
||||
- **概念解析** - 侧重于知识学习而非具体任务的深度文档。
|
||||
|
||||
### 模板
|
||||
|
||||
我们提供[操作指南模板](https://raw.githubusercontent.com/WordPress/gutenberg/trunk/docs/contributors/documentation/how-to-guide-template.md)来规范指南结构。如需创建新操作指南，可复制模板中的Markdown内容开始编写。
|
||||
|
||||
该模板基于"优质文档项目"的范例制作。如需创建高质量文档，可参考其[模板库](https://github.com/thegooddocsproject/templates)获取更多示例。
|
||||
|
||||
### 更新文档
|
||||
|
||||
更新现有页面的步骤：
|
||||
|
||||
1. 检出古腾堡代码库
|
||||
2. 创建功能分支，例如`docs/update-contrib-guide`
|
||||
3. 对现有文档进行必要修改
|
||||
4. 提交更改
|
||||
5. 使用[[Type] Developer Documentation](https://github.com/WordPress/gutenberg/labels/%5BType%5D%20Developer%20Documentation)标签创建拉取请求
|
||||
|
||||
### 创建新文档
|
||||
|
||||
添加新文档需要配置可运行的JavaScript开发环境来构建文档，请参阅[JavaScript构建设置文档](/docs/how-to-guides/javascript/js-build-setup.md)：
|
||||
|
||||
1. 在[docs](https://github.com/WordPress/gutenberg/tree/HEAD/docs)文件夹中创建Markdown文件，使用小写字母、无空格（如需分隔请使用连字符）及`.md`扩展名
|
||||
2. 使用markdown语法添加内容。所有文档必须包含且仅包含一个`h1`标签
|
||||
3. 在[toc.json](https://github.com/WordPress/gutenberg/blob/HEAD/docs/toc.json)层级结构中添加文档条目。格式请参考现有条目
|
||||
4. 运行`npm run docs:build`以更新`manifest.json`
|
||||
5. 将`manifest.json`与其他更新文件一并提交
|
||||
|
||||
如果忘记运行`npm run docs:build`，您的PR将无法通过静态分析检查，因为`manifest.json`文件存在未提交的本地变更必须被提交。
|
||||
|
||||
### 软件包文档编写
|
||||
|
||||
软件包文档由文档工具自动生成，通过提取软件包根目录下README.md文件的内容实现。但有时将README内容拆分为更易读的小节更为合适。
|
||||
|
||||
可通过在软件包中创建`docs`目录并添加`toc.json`文件来实现，该文件包含对`docs`目录下其他markdown文件的引用。`toc.json`文件应包含要作为主README文件子页面添加的页面数组，其格式遵循自动生成的[`manifest.json`](https://github.com/WordPress/gutenberg/blob/HEAD/docs/manifest.json)文件。
|
||||
|
||||
为确保这些页面嵌套在主软件包名称下，请正确设置`parent`属性。以下示例展示了如何为[`@wordpress/create-block`章节](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/)添加子页面：
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"title": "@wordpress/create-block 外部模板",
|
||||
"slug": "packages-create-block-external-template",
|
||||
"markdown_source": "../packages/create-block/docs/external-template.md",
|
||||
"parent": "packages-create-block"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### 链接使用规范
|
||||
|
||||
在某些情况下可能需要链接到其他内部文档页面。需要重点说明的是，所有文档可在不同上下文中浏览：
|
||||
|
||||
- 区块编辑器手册
|
||||
- GitHub网站
|
||||
- npm网站
|
||||
|
||||
要创建适用于所有上下文的链接，必须使用不带`https://github.com/WordPress/gutenberg`前缀的绝对路径链接。可通过以下模式引用文件：
|
||||
|
||||
- `/docs/*.md`
|
||||
- `/packages/*/README.md`
|
||||
- `/packages/components/src/**/README.md`
|
||||
|
||||
这样就能在上述三种上下文中正确处理链接。
|
||||
|
||||
请使用Gutenberg代码库中的完整目录和文件名（而非发布路径）；区块编辑器手册会生成短链接——您可以在教程部分看到这一点。同样地，手册中会省略`readme.md`部分，但链接中应包含该部分。
|
||||
|
||||
例如，本页面的链接为：`/docs/contributors/documentation/README.md`
|
||||
|
||||
<div class="callout callout-warning">
|
||||
<b>注意：</b>常规链接转换不适用于标注框内的链接。详见下文。
|
||||
</div>
|
||||
|
||||
### 代码示例规范
|
||||
|
||||
Markdown中的代码示例应使用三个反引号```` ``` ````包裹，并需包含语言标识符。请参阅[GitHub关于代码块的文档](https://help.github.com/en/github/writing-on-github/creating-and-highlighting-code-blocks)。
|
||||
|
||||
Gutenberg文档的独特功能是`codetabs`切换器，可同时显示两个版本的代码，常用于展示`JSX`和`Plain`代码示例。
|
||||
|
||||
以下是`codetabs`章节的示例：
|
||||
|
||||
````md
|
||||
\{\% codetabs \%\}
|
||||
\{\% JSX \%\}
|
||||
```js
|
||||
// JSX代码示例
|
||||
```
|
||||
\{\% Plain \%\}
|
||||
```js
|
||||
// 原生代码示例
|
||||
```
|
||||
\{\% end \%\}
|
||||
````
|
||||
|
||||
代码示例的首选格式是JSX，这应作为默认视图。源代码中排在第一的示例将作为默认显示。
|
||||
|
||||
**注意：** 并非每个指南都需要提供原生JavaScript代码示例。建议仅为入门教程或简短示例提供原生代码，但Gutenberg软件包及更广泛的React和JavaScript生态系统中的大多数代码都采用需要构建过程的JSX格式。
|
||||
294
docs/contributors/documentation/copy-guide.md
Normal file
294
docs/contributors/documentation/copy-guide.md
Normal file
@@ -0,0 +1,294 @@
|
||||
# 文案撰写指南
|
||||
|
||||
## 长文本规范
|
||||
|
||||
适用于编写多行/多步骤说明，或对页面功能进行叙述性引导的规范。
|
||||
|
||||
具体内容会随语境变化，但以下通用建议可供参考：
|
||||
|
||||
#### 第一：善用缩写形式！
|
||||
|
||||
缩写更符合对话习惯，能轻松让文本显得亲切自然（同时还能节省篇幅：可谓双赢）。
|
||||
|
||||
#### 第二：删减冗余表达
|
||||
|
||||
以下两种情形常出现堆砌词藻却不表意的情况：
|
||||
|
||||
首先是使用被动语态时：
|
||||
> 该区块可用于展示单张图片。
|
||||
|
||||
当看到“可用于”“被用于”等表述时需警惕：你正在使用被动语态。改用主动语态能让句子更简洁有力：
|
||||
> 该区块展示单张图片。
|
||||
|
||||
其次是回避明确断言而使用模糊表述时：
|
||||
> 图库区块可帮助您以优雅布局展示多张图片。
|
||||
|
||||
到底能不能？既然是我们开发的软件，就应该明确说明其功能：
|
||||
> 图库区块以优雅布局展示多张图片。
|
||||
|
||||
“允许您”这个短语也常被滥用：
|
||||
> 预格式化文本允许您保留制表符和换行符。
|
||||
|
||||
功能本身并不“允许”用户操作，它们只是实现特定目标的工具。直接说明其作用即可：
|
||||
> 预格式化文本会保留制表符和换行符。
|
||||
|
||||
更直接的表述往往更清晰。建议在审校时重点检查“可以”“能够”“可能”“允许您”“帮助”等高频冗余词，这些都是需要精简表述的常见信号。
|
||||
|
||||
#### 第三：慎用“简单”“便捷”“只需”
|
||||
|
||||
我们无权定义何为简单——这应由用户判定。若宣称某项操作简单，而用户实际体验却并非如此，会削弱用户对我们及产品的信任。“只需”同样如此——许多人知道避免使用“简单”，却频繁使用“只需”。“只需点击这里”“只需输入用户名”，这种表述暗示操作轻而易举，但我们无法预知用户可能遇到的困难。
|
||||
|
||||
具体说明往往更安全有效。“简单”和“便捷”常是我们未充分解释的托辞。遇到这些词时，请思考它们替代的具体含义。例如“按回车键添加区块很简单”实际想表达的是“您无需将手离开键盘即可为页面添加内容”。既然如此，何不直接说明具体优势？
|
||||
|
||||
当然并非要完全禁用这些词汇。当描述封面图区块需要更少配置，或介绍快速创建自定义区块工具时，完全可以说“封面图区块已简化”或“我们正让自定义区块创建更便捷”——此时这些词是相对且描述性的。重点是要避免将其用作绝对断言，并借机提供更具体明确的说明。
|
||||
|
||||
#### 第四：警惕“我们”滥用
|
||||
|
||||
当文本频繁出现“我们”，意味着焦点偏离了软件使用者而转向开发者。虽然有时确需如此，但多数情况下，重点应始终围绕用户需求及其获得的价值，而非“我们的成果”或“我们的意图”。
|
||||
|
||||
只有我们自己在意这些；用户要的只是好用的软件。若发现文本中“我们”频现，请考虑将表述重构为聚焦用户获益与成功体验。
|
||||
|
||||
#### 五、注意字母大小写规范
|
||||
|
||||
标题和副标题有两种书写格式：
|
||||
|
||||
**标题格式**：每个单词的首字母大写
|
||||
**句子格式**：仅句首单词首字母大写
|
||||
|
||||
功能名称和仪表板区域通常采用标题格式（如"站点统计"或"最新发布"），而功能标签则多使用句子格式（如"显示按钮"或"评论点赞功能"——其中"点赞"因作为功能名称需首字母大写，但整体标签仍遵循句子格式）。
|
||||
|
||||
当处理整页界面文本时，请确保同类文本（标题、工具提示、按钮等）保持统一的大小写规范。
|
||||
|
||||
## 错误信息撰写指南
|
||||
|
||||
如何编写清晰实用的错误信息
|
||||
|
||||
#### 一、重视错误信息中的语气与语调——它们传递着重要信息
|
||||
|
||||
语气语调传递的信息量不亚于文字本身。错误信息需要承载大量信息且通常要求简洁，但切忌牺牲语调的平衡，避免走向负面苛责或过度乐观的极端。
|
||||
|
||||
假设用户因权限不足无法发布文章，以下是我们应避免的表述方式：
|
||||
|
||||
> 您的用户角色不正确。
|
||||
|
||||
这种表述显得疏离冷漠。
|
||||
|
||||
> 停！您无权进行此操作。
|
||||
|
||||
这种表述带有不必要的警告意味和严厉感。
|
||||
|
||||
> 哎呀，我们不能让您这么操作哦！
|
||||
|
||||
这种表述显得过于轻佻。
|
||||
|
||||
即便在错误提示中，我们仍可保持直接、积极且友善的沟通。具体如何实现？请看第二至第四条建议！
|
||||
|
||||
#### 二、尽可能提供解决方案
|
||||
|
||||
优秀的错误信息不应仅停留在问题告知：
|
||||
|
||||
> 您的用户角色不正确。
|
||||
|
||||
然后呢？为什么这很重要？我该如何解决？这条信息对我有何帮助？用户需要了解角色权限的重要性，以及如何获取相应权限来完成目标操作。若错误信息未提供指导，用户将陷入困境——如果我们不明确说明，用户很可能重复触发相同的错误。
|
||||
|
||||
#### 三、避免为节省空间而滥用专业术语
|
||||
|
||||
> 您的用户角色不正确。请联系站点管理员。
|
||||
|
||||
这个版本似乎有所改进：至少指明了解决方向。
|
||||
|
||||
但细想仍存缺陷：用户仍不清楚自身角色定位及其重要性，也不明白"站点管理员"具体指代谁、如何联系。
|
||||
|
||||
虽然这条错误信息在技术上完全准确，但并未传递有效信息。若以理解和解决问题为目标，技术准确性未必能直接达成。
|
||||
|
||||
"您的账号暂无文章发布权限"虽未采用用户角色界面的专业术语，但清晰说明了问题症结，即使用户不了解"用户角色"概念也能理解。基于这种认知，即使提示信息止步于此，用户也能意识到需要申请权限。
|
||||
|
||||
与现有界面术语保持一致固然重要，但绝不能以牺牲理解为代价。
|
||||
|
||||
#### 四、切勿假定用户理解错误来源
|
||||
|
||||
> 您的用户角色不正确。
|
||||
|
||||
在我们看来，用户显然是在尝试发布内容或修改无权限设置时触发此提示。但对用户而言未必如此：用户往往会频繁点击操作，特别是在不确定如何完成某项任务时，未必能立即记起前序操作页面或设置项（及其意图）。
|
||||
|
||||
优秀的错误信息应包含引导用户的上下文提示。"您的账号暂无文章发布权限"既提醒了用户尝试发布文章的操作意图，也明确了触发错误的具体障碍所在。
|
||||
|
||||
## 项目符号列表
|
||||
|
||||
（顾名思义）撰写项目符号列表的指南
|
||||
|
||||
#### 第一：保持所有条目句式结构平行
|
||||
|
||||
平行结构能让列表更便于快速阅读——其可预测性能减轻读者的认知负担。
|
||||
|
||||
**优秀范例：**
|
||||
> 这个区块能实现什么功能？应有尽有！
|
||||
>
|
||||
> - 添加引用内容
|
||||
> - 高亮心仪链接
|
||||
> - 展示多张图片
|
||||
> - 创建项目符号列表
|
||||
|
||||
每个条目都是完整句子并以句号结尾（若列表均为单字或双字条目，通常可合并为常规单句——既提升可读性又节省空间）。每行皆以动词开头说明区块功能，且主语始终指向用户。用户能快速理解此列表，因为读完首条后即可掌握后续内容的阅读逻辑与信息类型。
|
||||
|
||||
**欠佳示例：**
|
||||
> 这个区块能实现什么功能？应有尽有！
|
||||
>
|
||||
> - 您可以添加引用内容
|
||||
> - 高亮您喜欢的链接
|
||||
> - 它能展示多张图片，很适合创建相册！
|
||||
> - 项目符号列表
|
||||
|
||||
本例中各行表述方式各异（有的以动词开头，有的以名词开头），句子主语不断切换（时而用户，时而区块），部分条目附加说明而部分没有，存在不完整句子且标点使用不统一。阅读此类列表需要耗费更多精力，因为读者必须逐条解析内容，无法预判各条目信息结构。
|
||||
|
||||
注意：这并非要求每个条目都必须简短且以行为动词开头！“可预测”不等于“简单化”，核心在于保持一致的句式结构。以下示例同样符合规范：
|
||||
> 这个区块能实现什么功能？应有尽有！
|
||||
>
|
||||
> - 尝试添加引用——有时他人的表述更为精妙！
|
||||
> - 用它高亮心仪链接，链接分享可是互联网的硬通货
|
||||
> - 创建展示多图的美术馆，尽情呈现您的摄影佳作
|
||||
|
||||
本例中各条目以更具用户视角的动词开头，并辅以补充信息增强趣味性。标点符号的灵活运用避免了刻板感，但由于基本结构一致，仍保持良好可读性。
|
||||
|
||||
#### 第二：犹豫不决时，以动词启句（但无需固守同一动词）
|
||||
|
||||
必须使用动词开头吗？非也。但若举棋不定，选择动词开头通常稳妥（尤其当列表描述系列动作或可选操作时）。在纯粹的操作说明中（如需要用户做出选择的界面文案），所有条目使用相同动词开头并无不可：
|
||||
|
||||
> 请选择后续操作：
|
||||
>
|
||||
> - 添加纯文本区块
|
||||
> - 添加引文区块
|
||||
> - 添加图片区块
|
||||
|
||||
若列表更具说服性质（如通过列举优势引导功能使用）或包含多步骤说明，则应变换动词以生动语言吸引读者：
|
||||
|
||||
> 这个区块能实现什么功能？应有尽有！
|
||||
>
|
||||
> - 尝试添加引用——有时他人的表述更为精妙！
|
||||
> - 用它高亮心仪链接，链接分享可是互联网的硬通货
|
||||
> - 创建展示多图的美术馆，尽情呈现您的摄影佳作
|
||||
|
||||
这些并非铁律——例如在说服性列表中，为增强聚焦性与冲击力亦可使用相同动词。但上述原则确是构建优质列表的基石。
|
||||
|
||||
#### 第三：当内容明显是列表时，无需刻意声明
|
||||
|
||||
**优秀范例：**
|
||||
> 这个区块能实现什么功能？应有尽有！
|
||||
>
|
||||
> - 添加引用内容
|
||||
> - 高亮心仪链接
|
||||
> - 展示多张图片
|
||||
|
||||
**欠佳示例：**
|
||||
> 这个区块能实现什么功能？应有尽有！以下是部分使用场景示例：
|
||||
>
|
||||
> - 您可以添加引用内容
|
||||
> - 高亮您喜欢的链接
|
||||
> - 它能展示多张图片，很适合创建相册！
|
||||
|
||||
要在极致清晰与信任用户之间找到平衡。一方面我们深知用户未必细读说明，另一方面冗余提示又易让用户产生被低估智商的感受。
|
||||
|
||||
#### 四、善用粗体突出重点
|
||||
|
||||
在项目符号列表中，粗体能引导读者关注核心信息。当列表项包含补充性次要内容时，这种方法尤为有效。
|
||||
|
||||
“关键信息”是精髓所在：粗体自带视觉引力，因此请始终聚焦每个列表项中最核心的内容：
|
||||
|
||||
> 这个区块有哪些功能？应有尽有！
|
||||
>
|
||||
> - 尝试插入**引述**——有时他人的精辟见解最值得分享
|
||||
> - 用它高亮你钟爱的**链接**——分享链接是互联网的硬通货
|
||||
> - 创建展示多张图片的**相册**，尽情呈现你的摄影佳作
|
||||
|
||||
反之，过度使用粗体会造成视觉混乱：
|
||||
|
||||
> **这个区块有哪些功能？** 应有尽有！
|
||||
>
|
||||
> - 尝试插入**引述**——有时他人的精辟见解最值得分享
|
||||
> - 用它高亮你钟爱的**链接**——分享**链接**是互联网的硬通货
|
||||
> - 创建展示**多张图片**的**相册**，尽情呈现你的最佳**摄影作品**
|
||||
|
||||
当列表简短基础时，无需使用粗体——徒增冗余：
|
||||
|
||||
> 这个区块有哪些功能？应有尽有！
|
||||
>
|
||||
> - 插入**引述**
|
||||
> - 高亮**链接**
|
||||
> - 展示多张**图片**
|
||||
|
||||
简洁的表述自带聚焦效果，无需额外强调。
|
||||
|
||||
## 界面描述指南
|
||||
|
||||
撰写功能简介或选项说明的单行文本规范
|
||||
|
||||
#### 一、清晰至上！
|
||||
|
||||
若用户无法理解选择某项功能将实现什么效果，再巧妙的双关语也毫无意义。文字游戏和俚语往往表意模糊，容易引发误解。如确需使用，应仅作为补充信息——绝不可用于解释核心功能——且必须确保能被广泛理解。
|
||||
|
||||
#### 二、呼应首章原则，警惕冗余表达
|
||||
|
||||
主动语态通常更优，在有限的界面空间里，精简表达对用户快速决策至关重要。以下对比可见如何通过精简实现更清晰的指引：
|
||||
|
||||
> 当您点击X时，将会触发Y效果
|
||||
|
||||
对比
|
||||
|
||||
> 点击X即可实现Y
|
||||
|
||||
虽然补充说明看似能引导用户，实则模糊了核心信息：
|
||||
|
||||
> 当您点击“设置”按钮时，弹窗将显示所有可用的高级设置
|
||||
|
||||
对比
|
||||
|
||||
> 点击“设置”访问高级选项
|
||||
|
||||
类似冗余表达还有“当您完成X后…”或“若需实现X…”。虽然在用户需要决策路径时后者确有必要，但多数情况下，“要实现X…”的简洁表达更为高效。
|
||||
|
||||
#### 三、明确具体
|
||||
|
||||
当操作需要前置条件时，必须明确说明具体要求及后续效果。避免使用“当您准备就绪时”这类模糊表述——准备什么？需具体说明前提条件。
|
||||
|
||||
“准备就绪”可能指：
|
||||
- 当需要添加新内容区块时
|
||||
- 当对文章内容满意时
|
||||
- 完成文章校对后
|
||||
- 当需要设置特色图片时
|
||||
- 完成所有参数配置后
|
||||
|
||||
包罗万象的表述实则毫无意义。指引越具体，实用性越强，用户对产品的信任度也越高。
|
||||
|
||||
#### 四、保留文字温度
|
||||
|
||||
虽以清晰为首要原则，且界面空间有限，但说明文字仍可保有感染力。
|
||||
|
||||
单行描述也应保持完整句式：
|
||||
> 列表。支持编号与符号形式
|
||||
|
||||
对比
|
||||
|
||||
> 添加列表，可选择编号或符号样式
|
||||
|
||||
适当使用缩略形式：
|
||||
> 添加列表。系统将提供格式选项
|
||||
|
||||
对比
|
||||
|
||||
> 添加符号列表——我们会提供格式选项
|
||||
|
||||
善用标点构建语言节奏：
|
||||
> 列表。支持编号与符号形式
|
||||
|
||||
对比
|
||||
|
||||
> 添加列表——编号或符号样式任君选择
|
||||
|
||||
坚持使用通俗表达：
|
||||
> 添加无序列表或有序列表
|
||||
|
||||
对比
|
||||
|
||||
> 添加列表，可选择编号或符号样式
|
||||
|
||||
（再次强调：请勿使用文字游戏！“感染力”在界面指引中应是含蓄的——我们要的是自然的人性化表达，而非刻意的俏皮话。）
|
||||
56
docs/contributors/documentation/how-to-guide-template.md
Normal file
56
docs/contributors/documentation/how-to-guide-template.md
Normal file
@@ -0,0 +1,56 @@
|
||||
# 操作指南模板
|
||||
|
||||
## 概述
|
||||
|
||||
操作指南通过一系列步骤引导用户完成单个任务。本指南的重点不在于概念教学，而是旨在回答"如何实现..."这一问题。
|
||||
|
||||
概述部分需总结问题所在，并可包含正确使用该解决方案的场景和背景信息。
|
||||
|
||||
## 开始之前
|
||||
|
||||
需包含前提条件和基本要求说明：
|
||||
|
||||
- 前提条件一：WordPress开发环境
|
||||
- 前提条件二：熟悉JavaScript和Gutenberg编辑器
|
||||
- 前提条件三：自定义区块或主题
|
||||
|
||||
在此处包含其他重要信息，例如已知问题或程序缺陷。
|
||||
|
||||
## 分步指南
|
||||
|
||||
本指南应包含循序渐进的指导说明。可使用代码片段、图片或截图辅助说明每个步骤。根据实际需要设置步骤数量，尽量保持每个步骤简洁明了。
|
||||
|
||||
### 步骤一：[可选标题]
|
||||
|
||||
阐述第一步操作的简要说明。
|
||||
|
||||
### 步骤二：[可选标题]
|
||||
|
||||
有序列表的引导语句：
|
||||
|
||||
1. 子步骤A
|
||||
2. 子步骤B
|
||||
3. 子步骤C
|
||||
|
||||
### 步骤三：[可选标题]
|
||||
|
||||
代码片段的解释说明。例如：
|
||||
|
||||
```shell
|
||||
npm install
|
||||
npm run build
|
||||
```
|
||||
|
||||
## 故障排除
|
||||
|
||||
- 可能出现哪些问题？
|
||||
- 潜在错误信息及应对措施？
|
||||
|
||||
## 结语
|
||||
|
||||
总结已完成的步骤，说明用户达成的目标。可附上相关文章链接、更复杂的示例，或提供深入学习的途径。
|
||||
|
||||
<!--
|
||||
本文档基于优质文档项目的模板编写。
|
||||
此注释可在您的指南中删除。
|
||||
-->
|
||||
Reference in New Issue
Block a user