风格指南

写得简单：一句话一个意思，用数字代替形容词。不用长破折号，改用前后带空格的连字符，不用分号，段落末尾不加句号

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

简洁优先

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

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

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

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

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

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

标点

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

不用长破折号。长破折号和短破折号完全不用。需要破折号的地方，写成前后带空格的连字符

修改前：Bullet Hero — less a game than a player for animations
修改后：Bullet Hero - less a game than a player for animations

中文不用任何破折号：不用——，不用—，甚至也不用前后带空格的连字符。改用，、：或另起一句

修改前：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。中文字体没有斜体，所以在中文里斜体只用于拉丁字母写的产品名，强调请用粗体
粗体用于强调一个词，或者让段落以它的主题开头
反引号用于一切技术性内容：文件、字段、格式、数值、按键、命令
版本总是写成前缀加版本号，放在反引号中：gv 1.0.0、sv 1.1.0、fv 1.0.0、bv 1.0.0、mg 2。从不写成单独的1.0.0，也不写“版本1.0.0”或不带前缀的“SDK 1.0.0”。反引号在title和# H1中不起作用，那里直接写gv 1.0.0。第三方的版本（Unity、NuGet包）不属于本项目，按原样书写
不用表情符号

标注框

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

标注框	英文标题	俄文标题	中文标题	用途
`> [!tip] Recommendation`	Recommendation	Рекомендация	建议	就这样做
`> [!tip]`	Tip	Подсказка	提示	捷径、技巧、更快的做法
`> [!info]`	Worth knowing	Интересно	须知	解释某个决定的背景
`> [!warning]`	Warning	Предупреждение	警告	这会耗费时间或降低质量
`> [!caution]`	Caution	Внимание	注意	这会毁掉成果，或导致发布一个有问题的关卡

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

语气

称呼读者为“你”（俄文用小写的敬称“вы”，英文用“you”）
项目以无人称的方式说话，从不自称“开发者”或“我们”。建议写成“建议”（俄文“рекомендуется”，英文“it is recommended”），事实以事物本身为主语：“游戏不附带任何纹理”
作者的观点或决定用第一人称，“我建议”（俄文“я рекомендую”，英文“I recommend”）。游戏由一个人制作，所以这里说“我”是诚实的。只用于真正的判断或决定，不用于陈述简单的事实
notes/中的笔记可以用第一人称，因为笔记是作者本人的报告
文档中不写历史。文档页面描述事物现在如何运作。“以前是X”属于笔记
不声称比别人更好。只有当比较能帮助读者更快理解时才可以使用
说明知识的边界。“很可能”“目前还不知道”。虚假的自信比不知道更糟
每个评价都附带理由。没有理由的形容词是缺陷
用数字代替形容词。秒、帧、兆字节、版本、物体数量
讽刺要冷，要少，放在括号里简短带过。参考页面几乎不用
任何语言都不用粗话，包括粗俗的替代词
永远不要编造地址、数字或事实。没有来源，就说它未知

页面开头

开头是回答，不是预告。它不描述页面（“X是什么，Y如何运作，Z在哪里”），而是简短地回答页面存在所要解决的问题。这样的开头本身就有用，即使读者不再往下读

核心放在第一段。它同时也是列表、搜索和链接预览中的描述：在200个字符处截断，不带链接和格式。回答可以延续到第二段和第三段

短页面不要拆开。如果内容不多，开头就与正文合并，而不是在顶部用单独一行重复正文

修改前：
在哪里报告错误或提问，以及写些什么才能让错误被重现

修改后：
游戏错误提交到releases的issues，问题发到Discord。附上设置中的版本字符串，以及出现错误之前的操作步骤

页面结构

# H1和回答页面问题的开头
正文不重复开头，而是给出细节、情况和步骤
##章节，每节一个主题：先是论点，然后是机制或步骤，最后是结论
适合的话，在末尾给出具体建议或“接下来阅读”的链接
结尾从不复述页面内容

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

什么会暴露出别人的文本

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

修改前后

开头段落

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

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

评价

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

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

尚不存在的东西

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

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

发起pull request前的检查

页面可以一眼扫过：一句话一个意思，细节放在页面下方或单独的页面
没有长破折号和短破折号（中文不用任何破折号）
段落、列表项和标题都不以句号结尾
没有粘连的行：每个独立的意思都是单独的段落，或在行内用句号隔开。中文段落在源文件中只占一行
没有分号、没有表情符号，感叹号最多一个
没有粗话
逗号、冒号和语法符合规范，没有错别字
每个评价旁边都有理由
数字、字段名和链接都取自来源
docs/中不出现“开发者”或“我们”：建议用无人称表达，“我”只用于作者的观点或决定
最多两个标注框
H1之后的开头回答页面的问题（核心在前200个字符内），不描述页面，也不在下文重复
结尾不复述页面内容

引用本页的页面