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

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

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

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

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

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

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

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

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

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

Пунктуация

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

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

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

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

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

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

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

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

Вёрстка

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

Выноски

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

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

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

Голос

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

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

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

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

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

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

До и после

Первый абзац

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

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

Оценка

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

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

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

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

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

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

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