如何编辑文档

本说明仅用于编辑英文文档。所有新信息必须先以英文添加。如果想翻译成其他语言（谢谢你），请使用 crowdin。

有关如何设置文本格式（标题、粗体等）和链接，请参阅本页的“代码语法”部分。

常规

如有问题、反馈或新想法，可以通过 discord 联系文档团队。

在某个阶段，团队可能会建议你创建拉取请求（PR）。PR 是将文档更改实际发布到 AAPS 网页的方式，网页内容存储在 GitHub 中。创建 PR 并不难，也是很好的贡献方式。你现在能读到这份文档，正是因为有人创建了 PR。不要担心犯错或编辑了错误文档；你的修改会在合并到“正式”的 AAPS 文档仓库前经过审核，意外不会破坏原始文件。通常流程如下：

编辑现有内容，修改和改进代码或文档；
仔细检查修改后的显示效果；
做一些变更说明，帮助他人理解修改内容；
创建拉取请求，请管理员采用你的修改；
团队会审核，并执行以下操作之一：(1)合并修改；(2)对修改发表评论；或 (3)使用你的修改创建新文档。

（补充说明：如果你是视觉型学习者，可以观看这个 YouTube 视频，了解 PR 工作流。）

下面以编辑 AndroidAPSdocs 为例。Windows PC、Mac 等任何可以访问互联网的电脑都可以完成这些操作。

访问 https://github.com/openaps/AndroidAPSdocs，点击右上角的 Fork，创建自己的仓库副本。

Fork 仓库

打开任意页面，导航到要编辑的页面。可以点击右上角的“Edit in GitHub”链接。此操作仅适用于英文页面。

编辑文档

也可以点击要编辑的页面内容顶部工具栏中的铅笔图标。需要先登录 GitHub 账户（如果还没有账户，注册过程很简单）。

RTD io

第 2 步的任一选项都会在你的仓库中创建一个新分支，并将修改保存在其中。编辑文件。

文档页面使用 Markdown，文件后缀为“.md”。Markdown 规范并非完全固定；目前我们使用 myst_parser 处理 Markdown 文件。请按照下面所述的正确语法操作。

编辑分支

你一直在“<>Edit file”标签页中工作。选择“Preview changes”标签页，重新检查所有修改是否符合预期（包括拼写）。如果发现需要改进的地方，返回编辑标签页继续修改。

预览模式

修改完成后，滚动到页面底部。在底部文本框“Add an optional extended description…”中填写说明。默认标题是文件名。尽量用一句话解释修改的原因，这样能帮助审核者理解你的 PR 目的。

提交说明

点击绿色的“Propose file changes”或“Commit changes”按钮。在出现的页面中点击“Create Pull Request”，然后在下一页再次点击“Create Pull Request”。

创建拉取请求

PR 已创建完成。GitHub 会为 PR 分配编号，显示在标题后的井号之后。返回此页面查看反馈（如果启用了 GitHub 邮件通知，也会收到 PR 活动邮件）。这次编辑会出现在 PR 列表中，团队将在提交到 AAPS 主文档前进行审核并可能提出反馈。想查看 PR 进度，可以点击 GitHub 账户右上角的铃铛图标查看所有 PR。

跟踪 PR

附言：你的 fork 和分支仍会保留在个人 GitHub 账户中。收到 PR 已合并的通知后，如果不再需要，可以删除分支（关闭或合并后，第 8 步的通知区域会提供删除分支的链接）。以后编辑时，按照上述流程操作，会始终从更新后的 AndroidAPSdocs 仓库版本开始。如果采用其他方式创建 PR（例如从 fork 仓库的 master 分支开始编辑），必须先执行“compare”并合并上次更新 fork 后产生的改动，以确保仓库是最新的。由于人们常忘记更新仓库，熟悉“compare”前，建议使用上述 PR 流程。

代码语法

文档页面使用 Markdown，文件后缀为“.md”。

Markdown 是一种非常简单的文本格式语言，将文本内容与文本格式分开。

作者只需标记某段内容是一级标题，Markdown 处理器就会在处理过程中生成必要的 HTML 代码，以便在 HTML 中渲染标题。

其理念是：

作者应先思考文本，而不是先思考格式；
Markdown 文本可以在不同 Markdown 工具之间交换，而不是依赖 Microsoft Windows 等专有工具；
一个 Markdown 文件可以生成多种输出格式。

Markdown 不是完全固定的标准。我们尽量接近标准，以便：

在 Markdown 工具和 Markdown SaaS 服务持续创新、需要更换工具时保持灵活；
允许使用翻译服务将英语翻译成法语、德语等目标语言。翻译服务可以处理 Markdown，但不能处理复杂格式代码，因为无法将内容与布局分开，这可能造成严重问题。

标题

一级标题：# headline
二级标题：## headline
三级标题：### headline
四级标题：#### headline

我们尽量避免使用更深层级的标题。

文本格式

粗体：**text**
斜体：*text*
粗斜体：***text***

有序列表

first
second
third

first
second
third

无序列表

- one element
- another element
- and another element

one element
another element
and another element

多级列表

在下一层级前增加 4 个空格，即可在列表中嵌套列表。

first
second
third
one element
another element
and another element
four
five
six

first
second
third
1. one element
2. another element
3. and another element
four
five
six

图片

使用以下 Markdown 语法插入图片。

图片：![alt text](../images/file.png)

图片应使用 PNG 或 JPEG 格式。

图片名称应符合以下命名规则。示例使用 png 后缀；如果使用 JPEG，请将后缀写为 jpeg。

filename-image-xx.png，其中 xx 是本文件中图片的唯一两位数字；
filename-image-xx.png，其中 xx 是对 md 文件作者有意义的名称。

英文语言的图片存放在 images 文件夹中，并由 Crowdin 自动传播到其他语言。无需进行其他操作！

目前不翻译图片：图片应包含尽可能少的文字，以便非英语读者访问。

图片应使用合理尺寸，在电脑、平板和手机上都能阅读。

网页截图最多 1050 像素宽；
流程图最多 1050 像素宽；
应用截图最多 500 像素宽。如无必要，不要并排放置截图。

链接

外部链接

外部链接指向外部网站。

外部链接：[alt text](www.url.tld)

指向 md 文件开头的内部链接

内部页面链接指向托管在本服务器上的 md 文件开头。

指向 .md 页面的内部链接：[alt text](../folder/file.md)

指向命名行内引用的内部链接

命名行内引用可以链接到托管在本服务器上的 md 文件中的任意位置，该位置设有可供跳转的引用。

在目标 md 文件中希望跳转到的位置添加命名引用。

(name-of-my-md-file-this-is-my-fancy-named-reference)=

引用名称在整个 AndroidAPSDocs md 文件集合中必须唯一，而不仅是在它所在的文件中唯一！

因此，良好做法是先写文件名，再写选定的引用名称。

只使用小写字母，并用连字符连接单词。

然后在文本中使用以下类型的链接指向该引用。

指向命名行内引用的内部链接：[alt text](name-of-my-md-file-this-is-my-fancy-named-reference)

注释、警告和可折叠注释

可以为文档添加注释框和警告框。

此外，还可以为详细信息添加可折叠注释，避免不关注细节的用户因页面太长而不愿阅读。请谨慎使用，因为文档应尽量易于阅读。

注释

```{admonition} Note headline
:class: note
This is a note.
```

Note headline

This is a note.

警告

```{admonition} Warning
:class: warning
This is a warning.
```

Warning headline

This is a warning.

可折叠注释

```
{admonition} further detailed readings for interested readers
:class: dropdown

This admonition has been collapsed,
meaning you can add longer form content here,
without it taking up too much space on the page.
```

供感兴趣读者进一步阅读的详细内容

此提示框默认折叠，因此可在此添加较长的内容，而不会在页面上占用过多空间。

表格

避免使用包含长文本的表格，因为 Markdown 中难以设置，通常无法适应手机屏幕宽度，翻译后也可能无法保持相同显示效果。

风格指南

内容

英语写作提示
AAPS 专用写作说明
实用参考资料

1. 英语写作提示

使用适合读者的语言

尽可能使用简单英语。这能帮助非母语读者，也有助于将 AAPS 文档翻译成其他语言。以与用户交谈的方式写作，想象你正坐在读者对面。记住，大多数 AAPS 用户没有编程背景。糖尿病本身也有许多术语和缩写。要考虑到有些人可能刚被诊断、糖尿病经验不如你，或接受过不同的糖尿病培训。若使用缩写，第一次出现时写出全称，并在括号中紧接着给出缩写，例如“超级微量大剂量 (SMB)”。同时链接到术语表。读者可能不熟悉的技术术语也可以在括号中补充说明。

不要写：“闭环中餐后血糖峰值升高的原因是什么？”

应写：“闭环中午餐后（餐后）血糖峰值升高的原因是什么？”

使用人人都能理解的朴素词语

这里可以找到帮助你简化写作的替代词 A–Z 列表：

https://www.plainenglish.co.uk/the-a-z-of-alternative-words.html

隐私和许可问题

尤其是录制视频或截图时，务必不要泄露私人信息（API key、密码）。确保 YouTube 内容不会被公开列出，而需要通过文档链接才能查看。避免引起对侵权版权材料（BYODA 等）的注意。

句子要短，直奔主题

清晰写作的平均句长应为 15 到 20 个单词。
这不意味着每个句子都要同样长。要有力度，通过混合短句和长句改变节奏。
每个句子坚持一个主要想法，最多再加一个相关要点。
解释复杂内容时可以出现偶尔的长句，但大多数长句都能拆分。
删除无力词语：“你可以”、“有”、“为了”。
将关键词放在标题、句子和段落的开头附近。
尽量提供简短图表、截图或视频，让内容直观。

不要害怕给出指令

命令是给出指示最快的方式，但作者有时害怕命令语气太强，于是写成“你应该这样做”而不是直接说“这样做”。可以在命令前加“请”来缓和语气；但如果某事必须完成，最好不要加“请”，否则读者可能认为可以拒绝。

不要写：“你应该把它当作一个完整的陈述句来考虑。”

应写：“把它当作一个完整的陈述句来考虑。”

多使用主动动词，少使用被动动词

主动动词示例：

“泵（主语）输送（动词）胰岛素（宾语）。”

这里“输送”是主动动词，句子先说明谁执行输送，再说明输送什么。

被动动词示例：

“胰岛素（主语）由泵（宾语）输送（动词）。”

这里*“输送”*是被动动词。与主动句相比，主语和宾语交换了位置。还需要引入“是”和“由”，使句子变长。也可以考虑使用主动动词。

不要写：“你可以通过 AAPS 泵菜单将泵连接到手机，并且有多种泵可供连接。”

应写：“通过 AAPS 泵菜单将所需的泵连接到手机。”

被动动词可能带来以下问题：

容易令人困惑；
往往使表达更冗长；
使文字缺乏活力。

适合使用被动语态的情况

有些时候使用被动语态是合适的：

让表达不那么生硬——“这张账单尚未支付”（被动）比“你尚未支付这张账单”（主动）语气柔和；
避免归责——“发生了错误”（被动），而不是“你犯了错误”（主动）；
不知道动作执行者是谁或是什么——“英格兰队已经选出”；
被动表达听起来更自然时。

避免名词化

名词化是指将非实体事物（例如过程、技术或情绪）改写成名词，通常由动词构成。

例如：

动词	名词化
complete	completion
introduce	introduction
provide	provision
fail	failure

名词化常被用来替代原来的动词，但会让人感觉没有真正发生任何动作。过多使用会使写作沉闷、难以阅读。

不要写：“该方法的实施已由一个团队完成。”

应写：“一个团队已经实施了该方法。”

适当使用列表

列表很适合拆分信息。主要有两种列表：

一个连续句子，在开头、中间或结尾列出若干要点；
带有引导语的独立项目符号。

上面的项目符号列表中，每个项目都是完整句子，因此以大写字母开头并以句号结束。相较于数字或字母，项目符号会突出每一点，同时不会增加额外的信息负担。

破除误区

可以用“和”“但是”“因为”“所以”或“然而”开头；
可以拆分不定式；
可以用介词结束句子；
如果找不到更好的词，句子中可以重复使用同一个词。

根据目的优化写作风格

为保持文档清晰简短，我们对文档不同部分使用不同风格。

介绍、背景和知识建立部分使用“解释”风格。

构建、配置 AAPS 以及部分故障排除部分使用“操作指南”风格（尽量少解释）。

教程帮助学习者获得基本能力；用户通过实践学习。

教程（例如教孩子打发蛋白）

叙述者直接与读者交谈：在本教程中，你将…… （少数情况下可以用“我们”，表达“我们共同完成”的思路）；
将来时：展示最终目标；
祈使语气：执行任务，使用具体步骤，避免抽象概念；
过去时：展示已完成的任务，给出快速、直接、可见的结果；
最少解释：只提供完成任务所必需的内容和原因；
忽略选项和替代方案，避免歧义；
步骤衔接：用引向下一步的句子结束当前步骤，使流程自然推进。例如： 你已经安装了 Let’s Encrypt 客户端，但在获取证书前，需要确认所有必需端口均已开放。下一步将更新防火墙设置。
标题“教程”（一级标题）；
引言（无标题）；
前置条件（二级标题）；
步骤：
第 1 步——完成第一项（二级标题）；
第 2 步——完成下一项（二级标题）；
第 n 步——完成最后一项（二级标题）；
结语（二级标题）。
- 教程语言：
  
  在本教程中，你将…… ——描述学习者将完成什么（不要写“你将学会……”）。
  
  首先，执行 x。现在，执行 y。完成 y 后，执行 z。 ——不留歧义或疑问。
  
  我们必须始终先执行 x 再执行 y，因为……（有关更多详细信息，请参阅“解释”。） ——用最基础的语言解释必要动作，并链接到更详细的解释。
  
  输出结果应类似于…… ——给出清晰的结果预期。
  
  请注意……记住…… ——提供线索，帮助学习者确认方向正确。
  
  你已经构建了一个安全的三层形态静态引擎…… ——描述并适度肯定学习者完成的成果（不要写“你已经学会了……”）。

操作指南（例如食谱）

操作指南的目的，是帮助已经具备能力的用户正确完成某项具体任务。

HOW-to；
叙述者直接与读者交谈：在本教程中，你将……；
将来时：展示最终目标；
条件祈使语气：为了得到 X，执行 y；使用具体步骤，避免抽象概念；
最少解释：只提供完成任务所必需的内容和原因；
忽略选项和替代方案，避免歧义，但可以链接到参考条目或解释条目；
标题“How-to”（一级标题）；
引言段落；
可选前置条件（若多于一项则使用二级标题）；
步骤：
第 1 步——完成第一项（二级标题）；
第 2 步——完成下一项（二级标题）；
第 n 步——完成最后一项（二级标题）；
结语段落。
- 操作指南语言：
  
  本指南将向你展示如何…… ——清楚描述指南帮助用户解决的问题或完成的任务。
  
  如果想要 x，就执行 y。要实现 w，就执行 z。 ——使用条件祈使句。
  
  如需完整的选项列表，请参阅 x 参考指南。 ——不要把所有可能与 x 相关的操作塞进实用指南，链接到参考条目即可。

解释（例如蛋白为何在打发时变硬背后的科学）

解释用于澄清、加深和拓展读者对主题的理解。

WHY；
以 About 开头；
提供背景并链接所有相关参考资料；
讨论选项和替代方案；
不要发出指令或提供操作参考（应链接到相关内容）；
说明未知因素、变化中的目标等；
标题“About”（一级标题）；
引言（无标题）；
可选前置条件（二级标题）；
子主题 1（二级标题）；
结语（二级标题）。
- 解释语言：
  
  x 的原因在于，从历史上看，y…… ——解释原因。
  
  w 优于 z，因为…… ——在适当情况下给出判断甚至观点。
  
  系统 y 中的 x 类似于系统 z 中的 w。不过…… ——提供有助于读者理解的背景。
  
  有些用户更喜欢 w（因为 z）。这可能是一个不错的方法，但是…… ——权衡替代方案。
  
  x 与 y 的交互如下：…… ——揭示系统内部机制，帮助读者理解某项功能为何如此工作。