Style guide

Write simply: one sentence, one thought, numbers instead of adjectives. A spaced hyphen instead of a long dash, no semicolons, no full stop at the end of a paragraph

The text reports, it does not sell. Every emotion is turned into a list, a table or a number first. A page that sounds like marketing, expert posturing or a friendly assistant has failed, even when every fact in it is right

Simple first

This rule stands above all the others

A text can have no filler at all and still be hard to read. Every sentence is true, but they are chained into one dense argument, and the reader has to hold all of it at once

Beginner pages are written so they can be skimmed. These are the player pages, the first pages for level authors, the quick start, the FAQ, help and the landing page of every section. Reference and SDK pages may be denser, but the same rules apply to their sentences

1. Only what the reader needs now. Before each sentence ask: will the reader act differently after reading it? If not, cut it or move it to the detailed page. Edge cases, platform caveats, internal reasons, how the site itself works - not for a beginner page
2. One sentence, one thought. No chains of clauses joined by colons, "because", "so", "while", no parentheses inside parentheses. Two short sentences beat one long one. A sentence may stand on its own line inside a paragraph: with a full stop at the end, except the last one. In Chinese, a sentence on its own line is a separate paragraph, with a blank line before it
3. The general rule, not the exceptions. "The numbers usually match" instead of three sentences on when they diverge. The exception lives on the detailed page, behind More - [[page]] (in Chinese 更多：[[page]])
4. Navigation before explanation. A landing page is a short intro and a table of name -> link, or lines like Everything you can download - [[download]]. Descriptive columns such as "what it is" and "status" are not needed when the link already says it
5. Say what matters, not how it works. "This number matters more than all the others" plus a link, instead of describing the mechanism
6. Status in a word. In development, Not available, Current version - gv 1.0.0. No "at the time of writing", no "no earlier than"
7. Expand an abbreviation where it first appears. For example, a column gv -> game version
8. Talk to the reader. A question and an answer are fine: Don't like the documentation? Then you can help write it. You may want to... is fine too
9. Plain words. A term appears only when the reader will meet it in the game UI. Then it is in backticks, exactly as the game shows it

Before (correct, but heavy):
The numbers do not follow each other. `gv` and `sv` once started equal and are now free to diverge: an SDK change does not have to move the game version, and a game update does not have to move the SDK version

After:
The version numbers do not have to follow each other, but in most cases they match.
Versions are also bumped together, and a shared update carries the same version

Punctuation

Punctuation follows the norms of the language, with two deliberate departures. Both are mandatory

No long dashes. The em dash and the en dash are not used at all. Wherever a dash is needed, write a hyphen with spaces around it

Before:  Bullet Hero — less a game than a player for animations
After:   Bullet Hero - less a game than a player for animations

Chinese uses no dash of any kind: no ——, no — and not even a spaced hyphen. Write ，, ： or a new sentence instead

Before:  Bullet Hero——与其说是游戏，不如说是动画播放器
After:   Bullet Hero与其说是游戏，不如说是动画播放器

No full stop at the end of a paragraph. Full stops between sentences inside a paragraph stay. The last sentence of a paragraph, a list item, a table cell and a heading get no full stop. Question and exclamation marks stay

Watch the line breaks. Markdown joins lines that have no blank line between them into one paragraph. A line with no full stop followed by another line turns into two sentences glued together

So in English and Russian, inside a paragraph, every line followed by another line ends with a full stop. Put a blank line before every separate thought

In Chinese, a paragraph is one line in the source. Markdown turns a line break inside a paragraph into a space, and that space shows up between Chinese sentences and gets in the way of search. So Chinese text is never wrapped by hand, and a sentence that must stand on its own line is a separate paragraph. Every separate thought gets a blank line before it

Other marks:

• The colon is the working mark for explaining and listing, use it freely
• The semicolon is never used. Write a full stop or a separate list item instead. Chinese does not use ； either: write two sentences or a ，
• Exclamation marks are rare, at most one per long text
• Quotes in English and Russian are straight "quotes" only, never «». Chinese uses full-width “”
• Parentheses are fine for a short aside, a caveat or a dry joke

Chinese

The rules above apply to every language with no exceptions. Chinese adds a few points:

• Address the reader as 你, never 您. Advice is 建议, the author's opinion is 我, never 开发者 or 我们
• Full-width punctuation ，。：？！（） and quotes “”. Code, file names and everything in backticks keep ASCII punctuation
• No space between hanzi and Latin letters or digits, the way the game itself writes it: 在Bullet Hero中, 60帧
• Kept in Latin letters: product and format names (Bullet Hero, JSON, BPM), file extensions, keys, field names
• Terms come from game/zh-glossary.md. Every term has one spelling, and rows marked strict are always followed. A UI label is quoted from the value of its key in game/zh.yaml
• Callout titles are 建议, 提示, 须知, 警告, 注意 (> [!tip] 建议)

Layout

• Short paragraphs, one to three lines
• A bulleted list for any enumeration longer than two items. Numbered lists only for steps and choices
• A table wherever three or more things are compared on several properties
• Italics (*text*) for terms, product names and genres: musical bullet hell, Project Arrhythmia. Chinese fonts have no italics, so in Chinese italics go only on product names written in Latin letters, and stress is bold
• Bold to stress one word or to open a paragraph with its subject
• Backticks for everything technical: files, fields, formats, values, keys, commands
• A version is always its prefix plus the number, in backticks: gv 1.0.0, sv 1.1.0, fv 1.0.0, bv 1.0.0, mg 2. Never a bare 1.0.0, "version 1.0.0" or "SDK 1.0.0" without the prefix. Backticks do not work in title and # H1, so there it is plain gv 1.0.0. Versions of third-party things (Unity, NuGet packages) are not ours and are written as they are
• No emoji

Callouts

A paragraph with one concrete purpose becomes a callout. There are exactly five, and the title is written in the page's language:

At most two callouts per page, because a third stops reading as emphasis. Reference pages may have two per section. A page about something that does not exist yet opens with a > [!warning] about its status, and that one does not count toward the limit

Voice

• Address the reader as "you" (in Russian, the formal "вы" in lowercase, in Chinese 你)
• The project speaks impersonally, never as "the developers" or "we". Advice is "it is recommended" (in Russian "рекомендуется", in Chinese 建议), and a fact has the thing itself as its subject: "The game ships no textures at all"
• The author's opinion or decision is in the first person, "I recommend" (in Russian "я рекомендую", in Chinese 我建议). The game is made by one person, so "I" is honest here. Only for a real judgement or decision, not for plain facts
• Notes in notes/ may speak in the first person, because a note is its author's report
• No history in docs. A docs page describes how things work now. "It used to be X" is a note
• No claims of being better. A comparison is allowed only when it helps the reader understand faster
• State the limits of knowledge. "Most likely", "not known yet". False confidence is worse than not knowing
• Every judgement comes with its reason. An adjective without a reason is a defect
• Numbers instead of adjectives. Seconds, frames, megabytes, versions, object counts
• Irony is dry and rare, a short aside in parentheses. Reference pages carry almost none
• No profanity in any language, including crude stand-in words
• Never invent an address, a number or a fact. With no source, say it is unknown

Page opening

The opening answers, it does not announce. It does not describe the page ("what X is, how Y works and where Z lies"), it gives a short answer to the question the page exists for. Such an opening is useful on its own, even if the reader goes no further

The core goes in the first paragraph. It is also the description in listings, search and link previews: cut at 200 characters, no links or formatting. The answer may continue into the second and third paragraphs

Do not split a short page. If there is little content, the opening merges with the body instead of repeating it as a separate line on top

Before:
Where to report a bug or ask a question, and what to write so the bug can be reproduced

After:
Game bugs go to the releases issues, questions to Discord. Attach the version string from the settings and the steps that lead to the bug

Structure of a page

1. # H1 and an opening that answers the page's question
2. The body does not repeat the opening, it gives the details, cases and steps
3. ## sections, one topic each: the claim, then the mechanism or the steps, then the conclusion
4. Where it fits, concrete advice or "read next" links at the end
5. The ending never retells the page

A guide page takes 2 to 4 minutes to read, about 2000 to 3500 characters. A reference page can be longer, but every section stands on its own

What gives away someone else's text

• a long dash, a full stop at the end of a paragraph, a semicolon
• "It's not just X, it's a whole Y"
• rule-of-three flourishes: "faster, cheaper, more reliable"
• empty openers: "in today's world", "let's dive in", "it's no secret that"
• a closing paragraph that repeats what was already said
• enthusiastic adjectives with no reason: "incredible", "amazing", "a powerful tool"
• polite filler and apologies to the reader
• symmetrical phrasing written for rhythm instead of meaning
• generic advice nobody checked against this game

Before and after

An opening paragraph

Before:
In today's world of level design, the Bullet Hero editor holds a special place — it's not just a
tool, it's a whole ecosystem. Let's dive in and see why.

After:
The editor builds a level from objects that live on a stretch of time and move along keyframes. Below is how it is arranged and in what order to work with it

A judgement

Before:
The Blob format is an amazing solution that dramatically speeds up loading and makes your workflow more productive.

After:
`Blob` loads faster than `Json`, but it cannot be read by eye or diffed in git. Keep a level in `Json` while you work on it and convert it to `Blob` before publishing

Something that does not exist yet

Before:
The official server will offer a convenient way to share your levels with the whole world.

After:
There is no official server yet. The protocol the game will use to talk to it has not been designed, so this page describes only what has already been decided

Checklist before a pull request

1. The page can be skimmed: one thought per sentence, details lower on the page or on their own page
2. No em dashes and no en dashes (Chinese uses no dash at all)
3. No paragraph, list item or heading ends with a full stop
4. No glued lines: every separate thought is its own paragraph or separated by a full stop within the line. A Chinese paragraph is one line in the source
5. No semicolons, no emoji, at most one exclamation mark
6. No profanity
7. Commas, colons and agreement follow the norm, no typos
8. Every judgement has its reason next to it
9. Numbers, field names and links come from a source
10. No "the developers" or "we" in docs/: advice is impersonal, "I" only for the author's opinion or decision
11. At most two callouts
12. The opening after the H1 answers the page's question (the core within the first 200 characters), does not describe the page and is not repeated below
13. The ending does not retell the page