スタイルガイド

シンプルに書きます。1文に1つの考え、形容詞より数字です。長いダッシュの代わりにスペースで囲んだハイフンを使い、セミコロンも段落末の句点も使いません

文章は報告するものであり、売り込むものではありません。感情はまずリスト、表、数字に置き換えます。宣伝、専門家ぶった態度、親しげなアシスタントのように聞こえるページは、事実がすべて正しくても失敗です

シンプルさを最優先に

このルールは他のすべてのルールより上にあります

無駄な言葉がまったくなくても、読みにくい文章はあります。どの文も正しいのに、それが1つの密な論証につながっていて、読者は全体を一度に頭に入れておかなければなりません

初心者向けのページは、流し読みできるように書きます。プレイヤー向けのページ、レベル作者向けの最初のページ、クイックスタート、FAQ、ヘルプ、各セクションのランディングページがこれに当たります。リファレンスやSDKのページはもっと密でもかまいませんが、文には同じルールが当てはまります

1. 読者が今必要なことだけ。各文の前に問いかけます：これを読んだ後、読者の行動は変わるか？変わらないなら、削るか詳細ページに移します。例外的なケース、プラットフォームごとの注意点、内部的な理由、サイト自体の仕組みは、初心者向けのページには載せません
2. 1文に1つの考え。コロン、「because」「so」「while」でつないだ節の連鎖も、括弧の中の括弧も使いません。長い1文より短い2文のほうが良い文章です。段落の中で文を1行に独立させることもできます：最後の文を除き、行末に句点を付けます。中国語と日本語では、独立した行の文は別の段落にし、前に空行を入れます
3. 例外ではなく一般的なルール。いつ食い違うかを3文で説明する代わりに「数字はたいてい一致します」と書きます。例外は詳細ページに置き、More - [[page]]（中国語では更多：[[page]]、日本語では詳細：[[page]]、スペイン語ではMás - [[page]]、ポルトガル語ではMais - [[page]]、フランス語ではPlus - [[page]]）でリンクします
4. 説明よりナビゲーション。ランディングページは短い導入と「名前 -> リンク」の表、またはダウンロードできるものはすべてこちら：[[download]]のような行で構成します。リンクを見ればわかるなら、「それは何か」や「状態」といった説明の列は要りません
5. 仕組みではなく、何が重要かを書く。仕組みを説明する代わりに、「この数字が他のどれよりも重要です」とリンクを書きます
6. 状態は一言で。開発中、利用不可、現在のバージョン：gv 1.0.0。「執筆時点では」や「早くても」は使いません
7. 略語は最初に出てきた箇所で展開する。たとえば列名gv -> ゲームバージョン
8. 読者に語りかける。問いと答えの形でもかまいません：ドキュメントが気に入りませんか？それなら書くのを手伝えます。〜したくなるかもしれませんも使えます
9. 平易な言葉。用語を出すのは、読者がゲームのUIでそれに出会うときだけです。そのときはバッククォートで囲み、ゲームの表示どおりに書きます

修正前（正しいが重い）：
バージョン番号は互いに連動しません。`gv`と`sv`はかつて同じ数字から始まり、今は自由に食い違えます：SDKを変更してもゲームのバージョンを上げる必要はなく、ゲームを更新してもSDKのバージョンを上げる必要はありません

修正後：
バージョン番号は互いに連動する必要はありませんが、ほとんどの場合は一致しています。バージョンは一緒に上げることもあり、共通の更新には同じバージョンが付きます

句読点

句読点はその言語の規範に従いますが、意図的な例外が2つあります。どちらも必須です

長いダッシュは使わない。エムダッシュもエンダッシュもまったく使いません。ダッシュが必要な箇所には、前後にスペースを入れたハイフンを書きます

修正前：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は、間に空行のない行を1つの段落につなげます。句点のない行の次に別の行が続くと、2つの文がくっついてしまいます

そのため英語、ロシア語、スペイン語、ポルトガル語、フランス語では、段落の中で次の行が続く行はすべて句点で終えます。独立した考えの前には必ず空行を入れます

中国語と日本語では、段落はソース上の1行です。Markdownは段落内の改行をスペースに変え、そのスペースが中国語や日本語の文の間に現れて検索の邪魔になります。そのため中国語と日本語の文章は手作業で折り返さず、1行に独立させる文は別の段落にします。独立した考えの前には必ず空行を入れます

その他の記号：

• コロンは説明と列挙のための実用的な記号です。自由に使ってください
• セミコロンは決して使いません。代わりに句点か、別のリスト項目にします。中国語でも；は使いません：2つの文にするか，を使います。日本語でも同じく、2つの文にするか、を使います
• 感嘆符はまれにしか使わず、長い文章でも1つまでです
• 引用符は英語、ロシア語、スペイン語、ポルトガル語、フランス語ではまっすぐな"引用符"だけを使い、«»は決して使いません。中国語は全角の“”、日本語は「」、韓国語は英語と同じまっすぐな引用符を使います
• 括弧は短い余談、ただし書き、さりげない冗談に使ってかまいません

中国語と日本語

上のルールは例外なくすべての言語に当てはまります。中国語にはいくつかの点が加わります：

• 読者は你で呼び、您は使いません。助言は建议、作者の意見は我で、开发者や我们は使いません
• 全角の句読点，。：？！（）と引用符“”を使います。コード、ファイル名、バッククォート内のすべてはASCIIの句読点のままです
• 漢字とラテン文字や数字の間にスペースを入れません。ゲーム自体の書き方と同じです：在Bullet Hero中、60帧
• ラテン文字のまま残すもの：製品名とフォーマット名（Bullet Hero、JSON、BPM）、ファイル拡張子、キー、フィールド名
• 用語はgame/zh-glossary.mdから取ります。どの用語も表記は1つで、strictの行には必ず従います。UIのラベルは、game/zh.yamlにあるそのキーの値から引用します
• コールアウトのタイトルは建议、提示、须知、警告、注意です（> [!tip] 建议）

日本語には次の点が加わります：

• です/ます調で書きます。読者を代名詞で呼ばず、あなたは使いません。主語は代名詞なしでわかるように文を組み立てます。助言は〜することをおすすめしますまたは推奨、作者の意見は私で、開発者や私たちは使いません
• 全角の句読点、。：？！（）と、かぎ括弧「」を使います。引用の中の引用は『』です。コード、ファイル名、バッククォート内のすべてはASCIIの句読点のままです
• 外来語はカタカナで書き、末尾のーを残します：インスペクター、レイヤー。Unity日本語版の表記と同じです
• かなや漢字とラテン文字や数字の間にスペースを入れません。ゲーム自体の書き方と同じです：Bullet Heroでは、60フレーム
• ラテン文字のまま残すもの：製品名とフォーマット名（Bullet Hero、JSON、BPM）、ファイル拡張子、キー、フィールド名
• 用語はgame/ja-glossary.mdから取ります。どの用語も表記は1つで、strictの行には必ず従います。UIのラベルは、game/ja.yamlにあるそのキーの値から引用します
• 句読点は太字の記号の外に置きます：**太字**。本文と書き、**太字。**本文とは書きません。後者はMarkdownが**を閉じられず、アスタリスクがそのまま表示されます
• コールアウトのタイトルは推奨、ヒント、補足、警告、注意です（> [!tip] 推奨）

韓国語では次の点を加えます：

• 합니다체で書きます（-ㅂ니다/-습니다）。読者を代名詞で呼ばず、당신は使いません。推奨は권장합니다、著者の意見は저で、개발자や저희は使いません
• 句読点はASCIIで、語の間はスペースで区切ります。英語と同じなので、上のダッシュ、句点、引用符の規則がそのまま適用されます
• 外来語はハングルで書きます。韓国語版Unityエディターの表記に合わせます：레이어、인스펙터
• ラテン文字の単語、コード、プレースホルダーの直後に助詞をそのまま付けません。文からは末尾の音がわからないため、을(를)、이(가)のような対の形にするか、言い換えます
• ラテン文字のまま残すもの：製品名と形式名（Bullet Hero、JSON、BPM）、ファイル拡張子、キー、フィールド名
• 用語はgame/ko-glossary.mdに従います。用語ごとに表記は1つで、strictの行は必ず守ります。UIのラベルはgame/ko.yamlにあるそのキーの値から引用します
• 太字の末尾の句読点やコードの直後に助詞が続くと太字が壊れます：**이름**을と書き、**"이름"**을とは書きません
• コールアウトのタイトルは권장、팁、참고、경고、주의です（> [!tip] 권장）

スペイン語では次の点を加えます：

• 中立的なスペイン語で書き、スペインとラテンアメリカで同じ1つのテキストを使います。読者は単数のtúで呼び、usted、vosotros、ustedesは使いません。助言はse recomiendaまたはconvieneで、te recomendamosは使いません。作者の意見はyoで、los desarrolladoresやnosotrosは使いません
• 大西洋の両側で同じように読める語彙を使います：ficheroではなくarchivo、ordenadorやcomputadoraではなくequipoまたはPC、celularではなくteléfonoまたはmóvil。画面をクリックするのはhacer clic、キーを押すのはpulsarです
• 読者の性別によって形が変わる形容詞は使いません（listo/lista）。言い換えて避けます
• 2つの例外はスペイン語の組版規則より優先されます：raya（長いダッシュ）の代わりにスペースで囲んだハイフン-を使い、挿入句や会話文でも同じです。«»の代わりにまっすぐな引用符を使います。段落、リスト項目、表のセル、見出しの末尾に句点を付けません。;は使いません
• ¿…?と¡…!は必ず両方の記号を付けます
• 見出しとタイトルは先頭の文字だけを大文字にします（## Cómo funciona el ajuste）。Title Caseにはしません。大文字でもアクセント記号を残します（Á、É）
• 翻訳せずに残すもの：製品名と形式名（Bullet Hero、JSON、BPM）、ファイル拡張子、キー、フィールド名
• 用語はgame/es-glossary.mdに従います。用語ごとに表記は1つで、strictの行は必ず守ります。UIのラベルは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は使いません
• ヨーロッパではなくブラジルの語彙を使います：ficheiroではなくarquivo、ecrãではなくtela、guardarではなくsalvar、ratoではなくmouse、telemóvelではなくcelular、transferirではなくbaixar。進行形はestarと現在分詞（está carregando）で書き、estar aと不定詞は使いません
• 読者の性別によって形が変わる形容詞は使いません（pronto/pronta）。言い換えて避けます
• 2つの例外はポルトガル語の組版規則より優先されます：travessão（長いダッシュ）の代わりにスペースで囲んだハイフン-を使います。«»や“”の代わりにまっすぐな引用符を使います。段落、リスト項目、表のセル、見出しの末尾に句点を付けません。;は使いません
• 見出しとタイトルは先頭の文字だけを大文字にします（## Como funciona o encaixe）。Title Caseにはしません。大文字でもアクセント記号を残します（É、Ã）
• 翻訳せずに残すもの：製品名と形式名（Bullet Hero、JSON、BPM）、ファイル拡張子、キー、フィールド名
• 用語はgame/pt-glossary.mdに従います。用語ごとに表記は1つで、strictの行は必ず守ります。UIのラベルは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）。言い換えて避けます
• 2つの例外はフランス語の組版規則より優先されます：tiret（ダッシュ）の代わりにスペースで囲んだハイフン-を使い、挿入句でも同じです。«»の代わりにまっすぐな引用符を使い、アポストロフィはまっすぐな'を使います。段落、リスト項目、表のセル、見出しの末尾に句点を付けません。;は使いません
• ?、!、:の前にはノーブレークスペース（U+00A0）を入れます。数字の後の%の前も同じです。普通のスペースにも、スペースなしにもしません。コードとバッククォートの中は元のテキストのままにします
• 見出しとタイトルは先頭の文字だけを大文字にします（## Comment fonctionne l'aimantation）。Title Caseにはしません。大文字でもアクセント記号を残します（É、À）
• 翻訳せずに残すもの：製品名と形式名（Bullet Hero、JSON、BPM）、ファイル拡張子、キー、フィールド名
• 用語はgame/fr-glossary.mdに従います。用語ごとに表記は1つで、strictの行は必ず守ります。UIのラベルはgame/fr.yamlにあるそのキーの値から引用します
• コールアウトのタイトルはRecommandation、Conseil、Bon à savoir、Avertissement、Attentionです（> [!tip] Recommandation）。詳細：[[page]]はPlus - [[page]]と書きます

レイアウト

• 段落は短く、1行から3行にします
• 箇条書きは2項目を超える列挙すべてに使います。番号付きリストは手順と選択肢だけに使います
• 表は、3つ以上のものを複数の性質で比較する場所すべてに使います
• 斜体（*text*）は用語、製品名、ジャンルに使います：musical bullet hell、Geometry Dash。中国語と日本語のフォントの斜体は当てにならないため、斜体はラテン文字で書かれた製品名にだけ使い、強調には太字を使います
• 太字は1語を強調するとき、または段落をその主題で始めるときに使います
• バッククォートは技術的なものすべてに使います：ファイル、フィールド、フォーマット、値、キー、コマンド
• バージョンは常に接頭辞と番号をバッククォートで囲んで書きます：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パッケージ）のバージョンはこのプロジェクトのものではないため、そのままの形で書きます
• 絵文字は使いません

コールアウト

具体的な目的を1つだけ持つ段落はコールアウトにします。コールアウトはちょうど5種類で、タイトルはページの言語で書きます：

コールアウトは1ページに2つまでです。3つ目からは強調として読まれなくなるためです。リファレンスのページではセクションごとに2つまで使えます。まだ存在しないものについてのページは、その状態を伝える> [!warning]で始めます。これは上限に数えません

文体

• 読者には「you」で語りかけます（ロシア語では小文字の敬称「вы」、中国語では你、スペイン語ではustedではなくtú、ポルトガル語ではvocê、フランス語ではvousではなくtu）。日本語では読者を代名詞で呼ばず、あなたは使いません
• プロジェクトは非人称で語り、「開発者」や「私たち」としては語りません。助言は「it is recommended」（ロシア語では「рекомендуется」、中国語では建议、日本語では〜することをおすすめしますまたは推奨、スペイン語ではse recomiendaまたはconviene、ポルトガル語ではrecomenda-seまたはvale a pena、フランス語ではil vaut mieuxまたはmieux vaut）とし、事実はそのもの自体を主語にします：「ゲームにはテクスチャがまったく含まれていません」
• 作者の意見や決定は一人称で書きます：「I recommend」（ロシア語では「я рекомендую」、中国語では我建议、日本語では私は〜をおすすめします）。ゲームは1人で作られているので、ここでの「私」は正直な表現です。本当の判断や決定にだけ使い、単なる事実には使いません
• notes/のノートは一人称で語ってかまいません。ノートはその作者の報告だからです
• ドキュメントに経緯は書きません。ドキュメントのページは、今どう動くかを説明します。「以前はXでした」はノートに書きます
• 優れていると主張しません。比較は、読者の理解を早める場合にだけ許されます
• 知識の限界を書きます。「おそらく」、「まだわかっていません」。誤った自信は、知らないことより悪いものです
• 判断には必ず理由を添えます。理由のない形容詞は欠陥です
• 形容詞より数字。秒、フレーム、メガバイト、バージョン、オブジェクトの数
• 皮肉は控えめに、まれに、括弧の中の短い余談として使います。リファレンスのページにはほとんど入れません
• どの言語でも罵り言葉は使いません。下品な言葉の言い換えも含みます
• アドレス、数字、事実を決して作り出しません。出典がなければ、不明だと書きます

ページの書き出し

書き出しは答えるものであり、予告するものではありません。ページを説明する（「Xとは何か、Yはどう動くか、Zはどこにあるか」）のではなく、そのページが存在する理由である問いに短く答えます。こうした書き出しは、読者がその先を読まなくてもそれだけで役に立ちます

核心は最初の段落に入れます。最初の段落は一覧、検索、リンクのプレビューでの説明文にもなります：200文字で切られ、リンクも書式も使えません。答えは2段落目、3段落目に続いてもかまいません

短いページは分けません。内容が少なければ、書き出しを冒頭の独立した1行として繰り返さず、本文とまとめます

修正前：
バグの報告や質問をする場所と、バグを再現できるように何を書くか

修正後：
ゲームのバグはreleasesのissuesへ、質問はDiscordへ。設定にあるバージョン文字列と、バグに至る手順を添えてください

ページの構成

1. # H1と、ページの問いに答える書き出し
2. 本文は書き出しを繰り返さず、詳細、ケース、手順を伝えます
3. ##のセクションは1つにつき1つの話題です：主張、次に仕組みか手順、最後に結論
4. 合う場合は、最後に具体的な助言か「次に読む」リンクを置きます
5. 結びでページ全体を繰り返しません

ガイドのページは読むのに2分から4分、英語でおよそ2000文字から3500文字です。リファレンスのページはもっと長くてもかまいませんが、各セクションがそれだけで成り立つようにします

他人の文章だとわかる特徴

• 長いダッシュ、段落末の句点、セミコロン
• 「それは単なるXではなく、Yそのものです」
• 3つ並べた飾り文句：「より速く、より安く、より確実に」
• 中身のない前置き：「現代の世界において」、「さっそく見ていきましょう」、「周知のとおり」
• すでに書いたことを繰り返す結びの段落
• 理由のない熱のこもった形容詞：「信じられない」、「驚くべき」、「強力なツール」
• 丁寧なだけの埋め草と、読者への謝罪
• 意味ではなくリズムのために書かれた対句
• このゲームで誰も確かめていない一般的な助言

修正前と修正後

冒頭の段落

修正前：
現代のレベルデザインの世界において、Bullet Heroのエディターは特別な位置を占めています——それは単なるツールではなく、ひとつのエコシステムそのものです。さっそく、その理由を見ていきましょう。

修正後：
エディターは、一定の時間だけ存在しキーフレームに沿って動くオブジェクトでレベルを組み立てます。以下では、その構成と作業の順序を説明します

判断

修正前：
Blobフォーマットは驚くべきソリューションで、読み込みを劇的に高速化し、ワークフローの生産性を高めます。

修正後：
`Blob`は`Json`より速く読み込めますが、目で読むことも、gitで差分を見ることもできません。作業中のレベルは`Json`で保存し、公開する前に`Blob`へ変換してください

まだ存在しないもの

修正前：
公式サーバーは、レベルを世界中と共有する便利な方法を提供します。

修正後：
公式サーバーはまだありません。ゲームがサーバーとの通信に使うプロトコルは設計されていないため、このページではすでに決まっていることだけを説明します

プルリクエスト前のチェックリスト

1. ページを流し読みできる：1文に1つの考え、詳細はページの下のほうか別のページにある
2. エムダッシュもエンダッシュもない（中国語と日本語ではダッシュ自体を使わない）
3. 段落、リスト項目、見出しが句点で終わっていない
4. 行がくっついていない：独立した考えはそれぞれ別の段落にするか、行の中で句点で区切っている。中国語と日本語の段落はソース上の1行
5. セミコロンも絵文字もなく、感嘆符は1つまで
6. 罵り言葉がない
7. 読点、コロン、文法が規範どおりで、誤字がない
8. どの判断にも理由が添えられている
9. 数字、フィールド名、リンクは出典に基づいている
10. docs/に「開発者」や「私たち」がない：助言は非人称、「私」は作者の意見や決定だけ
11. コールアウトは2つまで
12. H1の後の書き出しがページの問いに答えていて（核心は最初の200文字以内）、ページを説明せず、下で繰り返されていない
13. 結びでページ全体を繰り返していない