Руководство по стилю

Как должна звучать страница Bullet Hero: простота, пунктуация, голос, выноски и структура, с примерами до и после

Текст докладывает, а не продаёт. Любая эмоция сначала превращается в список, таблицу или число. Страница, которая звучит как реклама, экспертная поза или дружелюбный ассистент, провалена, даже если каждый факт в ней верен

Сначала простота

Это правило главнее всех остальных

Текст может быть без единого лишнего слова и всё равно читаться тяжело. Каждое предложение верно, но все они сцеплены в один плотный довод, и читателю приходится держать в голове всё сразу

Страницы для новичков пишутся так, чтобы их можно было пробежать глазами. Это страницы для игрока, первые страницы для автора уровней, быстрый старт, частые вопросы, помощь и стартовая страница каждого раздела. Справочные страницы и страницы SDK могут быть плотнее, но к их предложениям правила те же

Только то, что читателю нужно сейчас. Перед каждым предложением спросите: поступит ли читатель иначе, прочитав его? Если нет, уберите его или перенесите на подробную страницу. Частные случаи, оговорки о платформах, внутренние причины, устройство самого сайта - не для страницы новичка
Одно предложение - одна мысль. Никаких цепочек через двоеточия, "потому что", "поэтому", "при этом" и скобки в скобках. Два коротких предложения лучше одного длинного. Предложение может стоять на своей строке внутри абзаца: с точкой в конце, кроме последнего. В китайском предложение на своей строке - это отдельный абзац, с пустой строкой перед ним
Общее правило, а не исключения. "Номера обычно совпадают" вместо трёх предложений о том, когда они расходятся. Исключение живёт на подробной странице, за ссылкой Подробнее - [[page]] (в китайском 更多：[[page]])
Навигация раньше объяснения. Стартовая страница - это короткое вступление и таблица "название -> ссылка" или строки вида Всё, что можно скачать, - [[download]]. Описательные колонки вроде "что это" и "статус" не нужны, если ссылка уже всё говорит
Говорите, что важно, а не как устроено. "Это число важнее всех остальных" и ссылка вместо описания механизма
Статус одним словом. В разработке, Недоступно, Текущая версия - gv 1.0.0. Никаких "на момент написания" и "не раньше чем"
Раскрывайте сокращение там, где оно появилось впервые. Например, колонка gv -> game version
Говорите с читателем. Вопрос и ответ уместны: Не нравится документация? Тогда можете помочь в её написании. Вам может быть интересно... тоже уместно
Простые слова. Термин появляется, только если читатель встретит его в интерфейсе игры. Тогда он пишется в обратных кавычках, ровно как в игре

До (верно, но тяжело):
Номера не следуют друг за другом. `gv` и `sv` когда-то начинались одинаковыми, а теперь могут расходиться: изменение SDK не обязано двигать версию игры, а обновление игры не обязано двигать версию SDK

После:
Номера версий не обязаны друг за другом следовать, но в большинстве случаев они совпадают.
Также версии поднимаются одновременно, и общее обновление имеет одинаковую версию

Пунктуация

Пунктуация следует нормам языка, с двумя намеренными отступлениями. Оба обязательны

Никаких длинных тире. Длинное и среднее тире не используются вообще. Везде, где нужно тире, пишется дефис с пробелами вокруг

До:     Bullet Hero — не столько игра, сколько плеер для анимаций
После:  Bullet Hero - не столько игра, сколько плеер для анимаций

В китайском не используется никакое тире: ни ——, ни —, ни даже дефис с пробелами. Вместо него ，, ： или новое предложение

До:     Bullet Hero——与其说是游戏，不如说是动画播放器
После:  Bullet Hero与其说是游戏，不如说是动画播放器

Никакой точки в конце абзаца. Точки между предложениями внутри абзаца остаются. Последнее предложение абзаца, пункт списка, ячейка таблицы и заголовок точкой не заканчиваются. Вопросительный и восклицательный знаки остаются

Следите за переносами строк. Markdown склеивает строки без пустой строки между ними в один абзац. Строка без точки, за которой идёт другая строка, превращается в два слипшихся предложения

Поэтому в английском и русском внутри абзаца каждая строка, после которой идёт другая строка, заканчивается точкой. Перед каждой отдельной мыслью ставьте пустую строку

В китайском абзац - это одна строка в исходнике. Markdown превращает перенос строки внутри абзаца в пробел, и этот пробел появляется между китайскими предложениями и мешает поиску. Поэтому китайский текст никогда не переносится вручную, а предложение, которое должно стоять на своей строке, - это отдельный абзац. Перед каждой отдельной мыслью - пустая строка

Остальные знаки:

Двоеточие - рабочий знак для объяснений и перечислений, пользуйтесь им свободно
Точка с запятой не используется никогда. Вместо неё точка или отдельный пункт списка. В китайском ； тоже не используется: два предложения или ，
Восклицательные знаки редки, не больше одного на длинный текст
Кавычки в русском и английском только прямые "лапки", никогда «ёлочки». В китайском - полноширинные “”
Скобки уместны для короткого отступления, оговорки или сухой шутки

Китайский

Правила выше действуют для всех языков без исключений. В китайском к ним добавляется несколько пунктов:

К читателю обращаются на 你, никогда на 您. Совет - это 建议, мнение автора - 我, никогда не 开发者 и не 我们
Полноширинная пунктуация ，。：？！（） и кавычки “”. Код, имена файлов и всё в обратных кавычках сохраняют ASCII-пунктуацию
Между иероглифами и латиницей или цифрами пробела нет, как в самой игре: 在Bullet Hero中, 60帧
Латиницей остаются названия продуктов и форматов (Bullet Hero, JSON, BPM), расширения файлов, клавиши, названия полей
Термины берутся из game/zh-glossary.md. У каждого термина одно написание, а строки с пометкой strict соблюдаются всегда. Надпись интерфейса цитируется по значению её ключа в game/zh.yaml
Заголовки выносок - 建议, 提示, 须知, 警告, 注意 (> [!tip] 建议)

Вёрстка

Короткие абзацы, от одной до трёх строк
Маркированный список для любого перечисления длиннее двух пунктов. Нумерованные списки только для шагов и выбора
Таблица везде, где три и больше вещи сравниваются по нескольким свойствам
Курсив (*text*) для терминов, названий продуктов и жанров: musical bullet hell, Project Arrhythmia. В китайских шрифтах нет курсива, поэтому в китайском курсив ставится только на названия продуктов латиницей, а ударение - жирным
Жирный для ударения на одно слово или чтобы начать абзац с его предмета
Обратные кавычки для всего технического: файлов, полей, форматов, значений, клавиш, команд
Никаких эмодзи

Выноски

Абзац с одной конкретной целью становится выноской. Их ровно пять, и заголовок пишется на языке страницы:

Выноска	Заголовок на английском	Заголовок на русском	Заголовок на китайском	Что открывает
`> [!tip] Recommendation`	Recommendation	Рекомендация	建议	делайте так
`> [!tip]`	Tip	Подсказка	提示	короткий путь, приём, более быстрый способ
`> [!info]`	Worth knowing	Интересно	须知	контекст, который объясняет решение
`> [!warning]`	Warning	Предупреждение	警告	это будет стоить времени или качества
`> [!caution]`	Caution	Внимание	注意	это уничтожит работу или выпустит сломанный уровень

Не больше двух выносок на страницу, потому что третья перестаёт читаться как акцент. На справочных страницах можно по две на раздел. Страница о том, чего ещё нет, открывается выноской > [!warning] о статусе, и она в лимит не входит

Голос

Обращайтесь к читателю на "вы" (со строчной буквы, в английском "you", в китайском 你)
Проект говорит безлично, никогда не "разработчики" и не "мы". Совет - это "рекомендуется" (в английском "it is recommended", в китайском 建议), у факта подлежащее - сама вещь: "Игра не поставляет ни одной текстуры"
Мнение или решение автора - от первого лица, "я рекомендую" (в английском "I recommend", в китайском 我建议). Игру делает один человек, поэтому "я" здесь честно. Только для настоящей оценки или решения, не для простых фактов
Заметки в notes/ могут говорить от первого лица, потому что заметка - отчёт её автора
Никакой истории в документации. Страница документации описывает, как всё работает сейчас. "Раньше было X" - это заметка
Никаких заявлений о превосходстве. Сравнение допустимо, только когда оно помогает читателю понять быстрее
Называйте границы знания. "Скорее всего", "пока неизвестно". Ложная уверенность хуже незнания
У каждой оценки есть причина. Прилагательное без причины - дефект
Числа вместо прилагательных. Секунды, кадры, мегабайты, версии, количество объектов
Ирония сухая и редкая, короткое отступление в скобках. На справочных страницах её почти нет
Никакой обсценной лексики ни на одном языке, включая грубые заменители
Никогда не выдумывайте адрес, число или факт. Нет источника - скажите, что это неизвестно

Структура страницы

# H1 и описание в одну строку до 200 символов
Первый абзац отвечает на вопрос, а не готовит к нему: говорит, что это за вещь
Разделы ##, по одной теме: утверждение, затем механизм или шаги, затем вывод
Где уместно, в конце конкретные советы или ссылки "что читать дальше"
Концовка никогда не пересказывает страницу

Страница руководства читается за 2-4 минуты, это примерно 2000-3500 символов. Справочная страница может быть длиннее, но каждый её раздел самостоятелен

Что выдаёт чужой текст

длинное тире, точка в конце абзаца, точка с запятой
"Это не просто X, это целый Y"
тройки ради красоты: "быстрее, дешевле, надёжнее"
пустые зачины: "в современном мире", "давайте разберёмся", "ни для кого не секрет"
заключительный абзац, который повторяет уже сказанное
восторженные прилагательные без причины: "невероятный", "потрясающий", "мощный инструмент"
вежливые наполнители и извинения перед читателем
симметричные фразы ради ритма, а не смысла
общие советы, которые никто не проверял на этой игре

До и после

Первый абзац

До:
В современном мире левел-дизайна редактор Bullet Hero занимает особое место — это не просто
инструмент, это целая экосистема. Давайте разберёмся почему.

После:
Редактор собирает уровень из объектов, которые живут на отрезке времени и двигаются по ключевым кадрам. Ниже - как он устроен и в каком порядке с ним работать

Оценка

До:
Формат Blob - потрясающее решение, которое кардинально ускоряет загрузку и делает вашу работу продуктивнее.

После:
`Blob` загружается быстрее `Json`, но его нельзя прочитать глазами или сравнить в git. Держите уровень в `Json`, пока работаете над ним, и переводите в `Blob` перед публикацией

То, чего ещё нет

До:
Официальный сервер предложит удобный способ поделиться вашими уровнями со всем миром.

После:
Официального сервера пока нет. Протокол, по которому игра будет с ним общаться, не спроектирован, поэтому эта страница описывает только то, что уже решено

Проверка перед pull request

Страницу можно пробежать глазами: одна мысль в предложении, подробности ниже или на своей странице
Нет длинных и средних тире (в китайском нет никаких тире)
Ни один абзац, пункт списка или заголовок не заканчивается точкой
Нет слипшихся строк: каждая отдельная мысль - свой абзац или отделена точкой внутри строки. Китайский абзац в исходнике занимает одну строку
Нет точек с запятой, эмодзи, не больше одного восклицательного знака
Нет обсценной лексики
Запятые, двоеточия и согласование по норме, опечаток нет
У каждой оценки рядом есть причина
Числа, названия полей и ссылки взяты из источника
Нет "разработчиков" и "мы" в docs/: совет безличный, "я" только для мнения или решения автора
Не больше двух выносок
Первый абзац после H1 - описание в одну строку до 200 символов
Концовка не пересказывает страницу