風格指南

寫得簡單：一句話一個意思，用數字代替形容詞。不用長破折號，改用前後帶空格的連字元，不用分號，段落末尾不加句號

文本是在陳述，不是在推銷。任何情緒都要先變成列表、表格或數字。聽起來像廣告、像專家擺架子或像友好助手的頁面是失敗的，即使其中每條事實都正確

簡潔優先

這條規則高於其他所有規則

一段文本可以沒有一個多餘的字，卻依然難讀。每句話都是對的，但它們被串成一個密集的論證，讀者必須同時記住全部內容

面向新手的頁面要寫得能一眼掃過。這些頁面包括玩家頁面、關卡作者的入門頁面、快速入門、常見問題、幫助以及每個章節的首頁。參考頁面和SDK頁面可以更密集一些，但其中的句子遵循同樣的規則

1. 只寫讀者現在需要的。每寫一句話前先問：讀者讀完後會有不同的做法嗎？如果不會，就刪掉，或者移到詳細頁面。特殊情況、平臺注意事項、內部原因、網站本身如何運作，都不屬於新手頁面
2. 一句話，一個意思。不要用冒號、“因為”、“所以”、“同時”串起一連串分句，也不要括號套括號。兩個短句勝過一個長句。在英文和俄文中，句子可以在段落內單獨佔一行：以句號結尾，最後一句除外。在中文和日文裡，單獨成行的句子是單獨的段落，前面空一行
3. 寫一般規則，不寫例外。寫“版本號通常一致”，而不是用三句話說明何時不一致。例外放在詳細頁面，用更多：[[page]]連結過去（日文寫作詳細：[[page]]，西班牙文寫作Más - [[page]]，葡萄牙文寫作Mais - [[page]]，法文寫作Plus - [[page]]）
4. 先導航，後解釋。首頁是一段簡短的介紹加一張“名稱 -> 連結”的表格，或者像可以下載的一切：[[download]]這樣的行。如果連結本身已經說明了一切，就不需要“是什麼”“狀態”之類的描述列
5. 說什麼重要，而不是它如何運作。寫“這個數字比其他所有數字都重要”再加一個連結，而不是描述機制
6. 狀態用一個詞。開發中、暫不可用、當前版本：gv 1.0.0。不寫“在撰寫本文時”，也不寫“不早於”
7. 縮寫在第一次出現時展開。例如，列名gv -> game version
8. 與讀者對話。一問一答是可以的：不喜歡這份文件？那你可以幫忙一起寫。你也許想……也可以
9. 用平實的詞。只有當讀者會在遊戲介面中遇到某個術語時，才使用它。這時要把它放在反引號中，與遊戲中顯示的完全一致

修改前（正確，但很重）：
版本號並不相互跟隨。`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與其說是遊戲，不如說是動畫播放器

修改前：Bullet Hero——ゲームというより、アニメーションのプレイヤー
修改後：Bullet Heroはゲームというより、アニメーションのプレイヤー

段落末尾不加句號。段落內句子之間的句號保留。段落的最後一句、列表項、表格單元格和標題都不以句號結尾。問號和感嘆號保留

注意換行。Markdown會把中間沒有空行的幾行合併成一個段落。一行沒有句號而後面緊跟另一行，就會變成兩個粘在一起的句子

所以在英文、俄文、西班牙文、葡萄牙文和法文中，段落內凡是後面還有另一行的行，都要以句號結尾。每個獨立的意思前面都空一行

在中文和日文裡，一個段落在原始檔中就是一行。Markdown會把段落內的換行變成空格，這個空格會出現在中文或日文句子之間，還會妨礙搜尋。所以中文和日文從不手動換行，需要單獨成行的句子寫成單獨的段落。每個獨立的意思前面都空一行

其他標點：

• 冒號是解釋和列舉的常用標點，可以放心使用
• 分號永遠不用。改用句號或單獨的列表項。中文同樣不用；，改成兩句話或用，。日文也一樣，改成兩句話或用、
• 感嘆號要少用，一篇長文最多一個
• 引號：英文、俄文、西班牙文、葡萄牙文和法文只用直引號"quotes"，從不用«»。中文用全形引號“”，日文用「」，韓文和英文一樣用直引號
• 括號適合用於簡短的旁白、附加說明或冷幽默

中文和日文

上面的規則適用於所有語言，沒有例外。中文還有以下幾點：

• 稱呼讀者用你，從不用您。建議用建議，作者的觀點用我，從不用開發者或我們
• 使用全形標點，。：？！（）和引號“”。程式碼、檔名以及反引號中的一切都保留ASCII標點
• 漢字與拉丁字母或數字之間不加空格，與遊戲本身的寫法一致：在Bullet Hero中、60幀
• 保留拉丁字母：產品名和格式名（Bullet Hero、JSON、BPM）、副檔名、按鍵、欄位名
• 術語來自game/zh-glossary.md。每個術語只有一種寫法，標為strict的行必須遵守。引用介面文字時，使用game/zh.yaml中對應鍵的值
• 標註框標題是建議、提示、須知、警告、注意（> [!tip] 建議）

日文還有以下幾點：

• 使用です/ます體書寫。不用代詞稱呼讀者，從不用あなた，句子要寫得不用代詞也能看出主語。建議用〜することをおすすめします或推奨，作者的觀點用私，從不用開発者或私たち
• 使用全形標點、。：？！（）和直角引號「」。引語中的引語用『』。程式碼、檔名以及反引號中的一切都保留ASCII標點
• 外來語用片假名書寫，保留詞尾的ー：インスペクター、レイヤー。與日文版Unity的寫法一致
• 假名或漢字與拉丁字母或數字之間不加空格，與遊戲本身的寫法一致：Bullet Heroでは、60フレーム
• 保留拉丁字母：產品名和格式名（Bullet Hero、JSON、BPM）、副檔名、按鍵、欄位名
• 術語來自game/ja-glossary.md。每個術語只有一種寫法，標為strict的行必須遵守。引用介面文字時，使用game/ja.yaml中對應鍵的值
• 標點放在粗體標記之外：寫**太字**。本文，不寫**太字。**本文。後一種寫法中Markdown無法閉合**，星號會原樣顯示
• 標註框標題是推奨、ヒント、補足、警告、注意（> [!tip] 推奨）

韓文另外補充以下幾點：

• 使用합니다체語體（-ㅂ니다/-습니다）。不用代詞稱呼讀者，從不用당신。建議寫作권장합니다，作者的觀點用저，從不用개발자或저희
• 標點用ASCII，詞與詞之間用空格分隔，與英文相同，所以上面關於破折號、句號和引號的規則照常適用
• 外來詞用韓文字母書寫，與韓文版Unity編輯器的寫法一致：레이어、인스펙터
• 拉丁詞、程式碼或佔位符後面不直接接助詞，因為句子無法知道它的末音：寫成成對形式을(를)、이(가)，或者換一種說法
• 保留拉丁字母：產品和格式名稱（Bullet Hero、JSON、BPM）、副檔名、按鍵、欄位名
• 術語來自game/ko-glossary.md。每個術語只有一種寫法，標為strict的行必須遵守。介面標籤按game/ko.yaml中對應鍵的值引用
• 粗體末尾的標點或程式碼後面緊跟助詞時，粗體會失效：寫**이름**을，不要寫**"이름"**을
• 標註框標題是권장、팁、참고、경고、주의（> [!tip] 권장）

西班牙文另外補充以下幾點：

• 使用中性西班牙文，西班牙和拉丁美洲共用一份文本。稱呼讀者用單數的tú，從不用usted、vosotros或ustedes。建議寫作se recomienda或conviene，從不寫te recomendamos，作者的觀點用yo，從不用los desarrolladores或nosotros
• 用詞要讓大西洋兩岸的讀者讀起來一樣：用archivo而不用fichero，用equipo或PC而不用ordenador或computadora，用teléfono或móvil而不用celular，點選螢幕用hacer clic，按鍵用pulsar
• 不用隨讀者性別變化的形容詞（listo/lista），換一種說法避開
• 兩處例外在西班牙文排版規範之上照常適用：用前後帶空格的連字元-代替長破折號raya（插入語和對話中也一樣），用直引號代替«»，段落、列表項、表格單元格和標題末尾不加句號。不用;
• ¿…?和¡…!始終成對寫出兩個符號
• 標題只有第一個字母大寫（## Cómo funciona el ajuste），從不用Title Case。大寫字母保留重音符號（Á、É）
• 保留原文不翻譯：產品和格式名稱（Bullet Hero、JSON、BPM）、副檔名、按鍵、欄位名
• 術語來自game/es-glossary.md。每個術語只有一種寫法，標為strict的行必須遵守。介面標籤按game/es.yaml中對應鍵的值引用
• 標註框標題是Recomendación、Consejo、Conviene saber、Advertencia、Precaución（> [!tip] Recomendación）。更多：[[page]]寫作Más - [[page]]

葡萄牙文另外補充以下幾點：

• 使用巴西葡萄牙文，程式碼pt不帶地區。稱呼讀者用você，動詞用第三人稱，從不用tu、o senhor或vocês。建議寫作recomenda-se或vale a pena，從不寫recomendamos，作者的觀點用eu，從不用os desenvolvedores或nós
• 用巴西的詞彙，從不用歐洲的詞彙：用arquivo而不用ficheiro，用tela而不用ecrã，用salvar而不用guardar，用mouse而不用rato，用celular而不用telemóvel，用baixar而不用transferir。用estar加副動詞（está carregando），從不用estar a加不定式
• 不用隨讀者性別變化的形容詞（pronto/pronta），換一種說法避開
• 兩處例外在葡萄牙文排版規範之上照常適用：用前後帶空格的連字元-代替長破折號travessão，用直引號代替«»或“”，段落、列表項、表格單元格和標題末尾不加句號。不用;
• 標題只有第一個字母大寫（## Como funciona o encaixe），從不用Title Case。大寫字母保留變音符號（É、Ã）
• 保留原文不翻譯：產品和格式名稱（Bullet Hero、JSON、BPM）、副檔名、按鍵、欄位名
• 術語來自game/pt-glossary.md。每個術語只有一種寫法，標為strict的行必須遵守。介面標籤按game/pt.yaml中對應鍵的值引用
• 標註框標題是Recomendação、Dica、Vale saber、Aviso、Cuidado（> [!tip] Recomendação）。更多：[[page]]寫作Mais - [[page]]

法文另外補充以下幾點：

• 使用法國的法文，比利時、瑞士和加拿大的讀者讀起來也一樣。稱呼讀者用tu，從不用vous。建議寫作il vaut mieux或mieux vaut，從不寫nous te recommandons，作者的觀點用je，從不用les développeurs或nous
• 使用法文軟體的常用詞彙：fichier、paramètres、enregistrer、souris、écran，點選螢幕用cliquer，按鍵用appuyer sur
• 不用隨讀者性別變化的形容詞（prêt/prête），換一種說法避開
• 兩處例外在法文排版規範之上照常適用：用前後帶空格的連字元-代替破折號tiret（插入語中也一樣），用直引號代替«»，用直撇號'，段落、列表項、表格單元格和標題末尾不加句號。不用;
• ?、!和:前面加不換行空格（U+00A0），數字後的%前面也加，從不用普通空格，也從不省略。程式碼和反引號中的內容保持原樣
• 標題只有第一個字母大寫（## Comment fonctionne l'aimantation），從不用Title Case。大寫字母保留重音符號（É、À）
• 保留原文不翻譯：產品和格式名稱（Bullet Hero、JSON、BPM）、副檔名、按鍵、欄位名
• 術語來自game/fr-glossary.md。每個術語只有一種寫法，標為strict的行必須遵守。介面標籤按game/fr.yaml中對應鍵的值引用
• 標註框標題是Recommandation、Conseil、Bon à savoir、Avertissement、Attention（> [!tip] Recommandation）。更多：[[page]]寫作Plus - [[page]]

排版

• 段落要短，一到三行
• 專案符號列表用於任何超過兩項的列舉。編號列表只用於步驟和選項
• 表格用於在多個屬性上比較三樣或更多東西的場合
• 斜體（*text*）用於術語、產品名和型別名：musical bullet hell、Geometry Dash。中文和日文字型的斜體靠不住，所以在這兩種語言裡斜體只用於拉丁字母寫的產品名，強調請用粗體
• 粗體用於強調一個詞，或者讓段落以它的主題開頭
• 反引號用於一切技術性內容：檔案、欄位、格式、數值、按鍵、命令
• 版本總是寫成字首加版本號，放在反引號中：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包）不屬於本專案，按原樣書寫
• 不用表情符號

標註框

只有一個具體用途的段落寫成標註框。標註框正好五種，標題用頁面所屬的語言書寫：

每頁最多兩個標註框，因為第三個就不再像是強調了。參考頁面可以每個章節兩個。描述尚不存在之物的頁面以一個說明其狀態的> [!warning]開頭，這個不計入限制

語氣

• 稱呼讀者為“你”（俄文用小寫的敬稱“вы”，英文用“you”，西班牙文用tú而不用usted，葡萄牙文用você，法文用tu而不用vous）。日文不用代詞稱呼讀者，從不用あなた
• 專案以無人稱的方式說話，從不自稱“開發者”或“我們”。建議寫成“建議”（俄文“рекомендуется”，英文“it is recommended”，日文〜することをおすすめします或推奨，西班牙文se recomienda或conviene，葡萄牙文recomenda-se或vale a pena，法文il vaut mieux或mieux vaut），事實以事物本身為主語：“遊戲不附帶任何紋理”
• 作者的觀點或決定用第一人稱，“我建議”（俄文“я рекомендую”，英文“I recommend”，日文私は〜をおすすめします）。遊戲由一個人製作，所以這裡說“我”是誠實的。只用於真正的判斷或決定，不用於陳述簡單的事實
• notes/中的筆記可以用第一人稱，因為筆記是作者本人的報告
• 文件中不寫歷史。文件頁面描述事物現在如何運作。“以前是X”屬於筆記
• 不聲稱比別人更好。只有當比較能幫助讀者更快理解時才可以使用
• 說明知識的邊界。“很可能”“目前還不知道”。虛假的自信比不知道更糟
• 每個評價都附帶理由。沒有理由的形容詞是缺陷
• 用數字代替形容詞。秒、幀、兆位元組、版本、物體數量
• 諷刺要冷，要少，放在括號裡簡短帶過。參考頁面幾乎不用
• 任何語言都不用粗話，包括粗俗的替代詞
• 永遠不要編造地址、數字或事實。沒有來源，就說它未知

頁面開頭

開頭是回答，不是預告。它不描述頁面（“X是什麼，Y如何運作，Z在哪裡”），而是簡短地回答頁面存在所要解決的問題。這樣的開頭本身就有用，即使讀者不再往下讀

核心放在第一段。它同時也是列表、搜尋和連結預覽中的描述：在200個字元處截斷，不帶連結和格式。回答可以延續到第二段和第三段

短頁面不要拆開。如果內容不多，開頭就與正文合併，而不是在頂部用單獨一行重複正文

修改前：
在哪裡報告錯誤或提問，以及寫些什麼才能讓錯誤被重現

修改後：
遊戲錯誤提交到releases的issues，問題發到Discord。附上設定中的版本字串，以及出現錯誤之前的操作步驟

頁面結構

1. # H1和回答頁面問題的開頭
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. 結尾不復述頁面內容