风格指南

Bullet Hero的页面应该怎么写：简洁、标点、语气、标注框和结构，附修改前后的示例

文本是在陈述，不是在推销。任何情绪都要先变成列表、表格或数字。听起来像广告、像专家摆架子或像友好助手的页面是失败的，即使其中每条事实都正确

简洁优先

这条规则高于其他所有规则

一段文本可以没有一个多余的字，却依然难读。每句话都是对的，但它们被串成一个密集的论证，读者必须同时记住全部内容

面向新手的页面要写得能一眼扫过。这些页面包括玩家页面、关卡作者的入门页面、快速入门、常见问题、帮助以及每个章节的首页。参考页面和SDK页面可以更密集一些，但其中的句子遵循同样的规则

1. 只写读者现在需要的。每写一句话前先问：读者读完后会有不同的做法吗？如果不会，就删掉，或者移到详细页面。特殊情况、平台注意事项、内部原因、网站本身如何运作，都不属于新手页面
2. 一句话，一个意思。不要用冒号、“因为”、“所以”、“同时”串起一连串分句，也不要括号套括号。两个短句胜过一个长句。在中文里，单独成行的句子要写成单独的段落（前面空一行）
3. 写一般规则，不写例外。写“版本号通常一致”，而不是用三句话说明何时不一致。例外放在详细页面，用更多：[[page]]链接过去
4. 先导航，后解释。首页是一段简短的介绍加一张“名称 -> 链接”的表格，或者像可以下载的所有内容都在这里：[[download]]这样的行。如果链接本身已经说明了一切，就不需要“是什么”“状态”之类的描述列
5. 说什么重要，而不是它如何运作。写“这个数字比其他所有数字都重要”再加一个链接，而不是解释机制
6. 状态用一个词。开发中、不可用、当前版本：gv 1.0.0。不写“在撰写本文时”，也不写“计划不早于”
7. 缩写在第一次出现时展开。例如，列名gv -> 游戏版本
8. 与读者对话。一问一答是可以的：不喜欢这份文档？那你可以帮忙写。你可能想要……也可以
9. 用平实的词。只有当读者会在游戏界面中遇到某个术语时，才使用它。这时要把它放在反引号中，与游戏中显示的完全一致

修改前（正确，但很重）：
版本号并不相互跟随。`gv`和`sv`曾经从相同的数字开始，现在可以自由地分开：SDK的改动不必推动游戏版本，游戏的更新也不必推动SDK版本

修改后：
版本号不必彼此一致，但大多数情况下是一致的。版本也会一起提升，共同的更新带有相同的版本号

标点

标点遵循各语言的规范，但有两处有意的例外。两处都是强制的

不用破折号。英文和俄文中完全不用长破折号和短破折号，需要破折号的地方写成前后带空格的连字符。中文不用任何破折号：不用——，不用—，也不用前后带空格的连字符，改用，、：或另起一句

修改前：Bullet Hero——与其说是游戏，不如说是动画播放器
修改后：Bullet Hero与其说是游戏，不如说是动画播放器

段落末尾不加句号。段落内句子之间的句号保留。段落的最后一句、列表项、表格单元格和标题都不以句号结尾。问号和感叹号保留

注意换行。Markdown会把中间没有空行的几行合并成一个段落。在英文和俄文中，一行没有句号而后面紧跟另一行，就会变成两个粘在一起的句子。所以在这两种语言里，段落内凡是后面还有另一行的行，都要以句号结尾

在中文里，一个段落在源文件中就是一行。Markdown会把段落内的换行变成空格，这个空格会出现在中文句子之间，还会影响搜索。所以中文从不手动换行，需要单独成行的句子写成单独的段落。每个独立的意思前面都空一行

其他标点：

• 冒号是解释和列举的常用标点，可以放心使用
• 分号永远不用。改用句号或单独的列表项。中文同样不用；，改成两句话或用，
• 感叹号要少用，一篇长文最多一个
• 引号：英文和俄文只用直引号"quotes"，从不用«»。中文用全角引号“”
• 括号适合用于简短的旁白、附加说明或冷幽默

中文

上面的规则适用于所有语言，没有例外。中文还有以下几点：

• 称呼读者用“你”，从不用“您”。需要称呼项目时，用“开发者”
• 使用全角标点，。：？！（）和引号“”。代码、文件名以及反引号中的一切都保留ASCII标点
• 汉字与拉丁字母或数字之间不加空格，与游戏中的写法一致：在Bullet Hero中、60帧
• 保留拉丁字母：产品名和格式名（Bullet Hero、JSON、BPM）、文件扩展名、键盘按键、字段名
• 术语来自game/zh-glossary.md，每个术语只有一种写法，标为strict的行必须遵守。引用界面标签时，使用game/zh.yaml中对应键的值
• 标注框标题是建议、提示、须知、警告、注意（> [!tip] 建议）

排版

• 段落要短，一到三行
• 项目符号列表用于任何超过两项的列举。编号列表只用于步骤和选项
• 表格用于在多个属性上比较三样或更多东西的场合
• 斜体（*text*）用于术语、产品名和类型名：musical bullet hell、Project Arrhythmia。中文字体没有斜体，所以在中文里斜体只用于拉丁字母写的产品名，强调请用粗体
• 粗体用于强调一个词，或者让段落以它的主题开头
• 反引号用于一切技术性内容：文件、字段、格式、数值、按键、命令
• 不用表情符号

标注框

只有一个具体用途的段落写成标注框。标注框正好五种，标题用页面所属的语言书写：

每页最多两个标注框，因为第三个就不再像是强调了。参考页面可以每个章节两个。描述尚不存在之物的页面以一个说明其状态的> [!warning]开头，这个不计入限制

语气

• 称呼读者为“你”（俄文用敬称вы，英文用you）。在文档页面上永远不说“我”。需要称呼项目时，用“开发者”。notes/中的笔记可以用第一人称，因为笔记是作者本人的报告
• 文档中不写历史。文档页面描述事物现在如何运作。“以前是X”属于笔记
• 不声称比别人更好。只有当比较能帮助读者更快理解时才可以使用
• 说明知识的边界。“很可能”“目前还不知道”。虚假的自信比不知道更糟
• 每个评价都附带理由。没有理由的形容词是缺陷
• 用数字代替形容词。秒、帧、兆字节、版本、物体数量
• 讽刺要冷，要少，放在括号里简短带过。参考页面几乎不用
• 任何语言都不用粗话，包括粗俗的替代词
• 永远不要编造地址、数字或事实。没有来源，就说它未知

页面结构

1. # H1和一行不超过200个字符的摘要
2. 第一段直接回答问题，而不是为回答做铺垫：先说这是什么
3. ##章节，每节一个主题：先是论点，然后是机制或步骤，最后是结论
4. 适合的话，在末尾给出具体建议或“接下来阅读”的链接
5. 结尾从不复述页面内容

一篇指南页面需要2到4分钟读完，大约2000到3500个字符。参考页面可以更长，但每个章节都要能独立成立

什么会暴露出别人的文本

• 破折号、段落末尾的句号、分号
• “这不仅仅是X，更是一个完整的Y”
• 为了好听而凑的三连：“更快、更便宜、更可靠”
• 空洞的开场白：“在当今世界”“让我们深入了解”“众所周知”
• 重复前文内容的结尾段落
• 没有理由的热情形容词：“难以置信的”“惊人的”“强大的工具”
• 客套的填充语和对读者的道歉
• 为了节奏而写的对称句式，而不是为了意思
• 没有针对这款游戏验证过的泛泛建议

修改前后

开头段落

修改前：
在当今的关卡设计领域，Bullet Hero编辑器占据着特殊的地位——它不仅仅是一个工具，更是一个完整的生态系统。让我们深入了解一下原因。

修改后：
编辑器用物体搭建关卡，物体存在于一段时间内，并沿着关键帧移动。下面介绍它的结构，以及按什么顺序使用它

评价

修改前：
Blob格式是一个惊人的解决方案，它极大地加快了加载速度，让你的工作流程更加高效。

修改后：
`Blob`比`Json`加载更快，但它无法直接阅读，也无法在git中比较差异。制作关卡期间请保持`Json`格式，发布前再转换为`Blob`

尚不存在的东西

修改前：
官方服务器将提供一种便捷的方式，让你与全世界分享你的关卡。

修改后：
官方服务器目前还不存在。游戏与它通信所用的协议尚未设计，所以本页只描述已经确定的内容

发起pull request前的检查清单

1. 页面可以一眼扫过：一句话一个意思，细节放在页面下方或单独的页面
2. 没有长破折号和短破折号（中文不用任何破折号）
3. 段落、列表项和标题都不以句号结尾
4. 没有粘连的行：每个独立的意思都是单独的段落，或在行内用句号隔开。中文段落在源文件中只占一行
5. 没有分号、没有表情符号，感叹号最多一个
6. 没有粗话
7. 逗号、冒号和语法符合规范，没有错别字
8. 每个评价旁边都有理由
9. 数字、字段名和链接都有来源
10. docs/中不出现“我”，项目称为“开发者”
11. 最多两个标注框
12. H1之后的第一段是一行不超过200个字符的摘要
13. 结尾不复述页面内容