📖 Гайдлайн по документации RimLoc¶

Коротко: пишем так, чтобы и новичок‑переводчик, и разработчик нашли ответы быстро, с примерами и понятными словами. Эту страницу используем как «единый стандарт» при добавлении новых страниц и обновлении существующих.

Для кого пишем (аудитории)¶

Новичок/переводчик: не знает терминов и не пишет код. Нужны пошаговые инструкции, реальные примеры команд, скриншоты, минимум жаргона.
Разработчик: собирает из исходников, пишет код/плагины, правит CLI. Нужны команды, ссылки на исходники, тесты, архитектура.

Каждая страница отвечает обеим аудиториям: в начале — «Почему это важно» и простой сценарий, ниже — подробности и ссылки для разработчиков.

Стиль и тон¶

Пишем простым дружелюбным языком. Без лишней теории — сразу к делу.
В начале страницы кратко объясняем ценность: зачем это нужно пользователю и чем RimLoc помогает.
Добавляем подсказки, предупреждения и примеры через блоки:

!!! tip "💡 Совет"
    Короткая полезная рекомендация.

!!! warning "⚠️ Важно"
    Что сломается, если сделать не так.

!!! example "✅ Пример"
    Команда и ожидаемый результат.

В каждом руководстве — реальные команды CLI и фрагмент вывода. Проверяем, что примеры запускаются.
Используем эмодзи умеренно, чтобы быстрее сканировать текст: 💡⚠️✅🚀.

Термины и глоссарий¶

Любой технический термин объясняем «на месте» простыми словами и/или даём ссылку на глоссарий.
Первое упоминание термина — со ссылкой в Словарь: ../glossary.md#плейсхолдер.
Если нужен внешний источник — добавляем ссылку (например, Poedit, Git, Cargo).
Новые термины обязателен к добавлению в docs/ru/glossary.md (и зеркало в EN).

Примеры ссылок:

Плейсхолдеры: ../glossary.md#плейсхолдер
PO‑файл: ../glossary.md#po-portable-object (в EN: ../glossary.md#po-portable-object)

Структура документации¶

Рекомендуемая карта (зеркалится в EN):

🚀 Quick Start: getting-started.md
Туториалы (пошаговые):
«Как перевести мод с нуля»: tutorials/translate_mod.md
«Как обновить перевод»: tutorials/update_translations.md
«Как экспортировать в .po»: tutorials/export_po.md
Функции RimLoc (CLI): cli/*.md — для каждой команды кратко «Зачем это нужно» и примеры.
Форматы и концепции: guide/*.md — конфиг, плейсхолдеры, PO и т. п.
Разработчикам: dev/*.md — сборка, тестирование, публикация, стиль доков (эта страница).
FAQ: faq.md
Troubleshooting: troubleshooting.md
Словарь: glossary.md

Навигация строится в mkdocs.yml; RU и EN должны иметь одинаковые разделы.

Кросс‑ссылки и примеры¶

Внутри гайдов даём ссылки на соответствующие команды CLI. Пример: «См. validate: ../cli/validate.md».
Термины всегда ссылаем в Словарь.
В технических разделах — ссылки на Poedit, Git, Cargo, VS Code и др.
Скриншоты складываем в docs/assets/ с понятными именами (cli-validate-ok.png) и alt‑текстом. Размеры оптимизируем.

Шаблон короткого примера:

rimloc-cli validate --root ./Mods/MyMod --format text
# Ожидаем: список предупреждений; код выхода 1 при ошибках

Форматирование¶

Заголовки: h1 — один на страницу, далее h2/h3.
Списки и таблицы — когда нужно сравнивать опции/режимы.
Код и конфиги — в блоках с языком (bash, toml, json).
Адмонишены (!!! tip/warning/example) — для советов, важных моментов и примеров.

Таблица сравнения (пример):

Команда	Когда использовать	Ключевой флаг
`validate`	Проверка качества перевода	`--format`
`diff-xml`	Сравнение оригинала/перевода	`--baseline-po`
`xml-health`	Проверка структуры XML	`--lang-dir`

Шаблоны страниц¶

Начало любой инструкции:

# Название страницы

Коротко: зачем это нужно и что получите в конце.

## 🚀 Быстрый план
1) … 2) … 3) …

!!! tip "💡 Совет"
    …

## Шаг 1. …
Команда/скриншот/ожидаемый вывод.

## Что дальше
См. также: ссылки на CLI/гайды/Словарь.

Страница команды CLI начинается с блока «Зачем это нужно», затем «Как использовать» и «Примеры».

Поддержка и обновления¶

Любая новая команда/флаг CLI → страница в docs/*/cli/ + обновление примеров.
Любой новый термин → добавляем в glossary.md (RU/EN).
Новая фича → как минимум одна пошаговая страница или раздел «Как использовать».
README.md держим кратким: обзор + быстрый старт + ссылка на сайт документации.

Чек‑лист для PR, затрагивающего доки:

[ ] Есть раздел «Почему это важно» и «Шаги».
[ ] Есть реальные команды и проверенный вывод.
[ ] Термины ссылаются в Словарь.
[ ] Добавлены/обновлены RU и EN версии страницы.
[ ] mkdocs build проходит без битых ссылок.

Баланс для новичков и разработчиков¶

Сначала — что сделать (простые шаги), затем — как это работает (детали).
Новички видят готовые команды и скриншоты; разработчики — ссылки на исходники, схемы, тесты.
Избегаем перегрузки теорией; углубления — по ссылкам «см. также».

Где править и как проверять¶

Файлы: docs/ru/** и docs/en/** (структура зеркальная).
Локально: python -m venv .venv && source .venv/bin/activate && pip install -r requirements-docs.txt && mkdocs serve.
Перед релизом: SITE_URL=… mkdocs build для проверки абсолютных ссылок.