Перейти к содержимому

Как дополнять документацию

Документацию пишут те, кто делает миссии. Если вы разобрались, как что-то настроить, и на это ушло больше десяти минут — запишите, следующий потратит одну.

Нужен аккаунт на GitHub. Каждая правка проходит проверку и после неё появляется на сайте в течение нескольких минут.

  1. Внизу страницы нажмите Редактировать страницу — GitHub откроет её исходный файл.
  2. Внесите правку.
  3. Нажмите Commit changes…, коротко опишите, что поменяли, затем Propose changes и Create pull request.
  1. Откройте нужную папку в репозитории: справочник — reference/.
  2. Нажмите Add file → Create new file.
  3. Назовите файл латиницей через дефис — имя станет адресом страницы: reference/kill-zones.md → /reference/kill-zones/.
  4. Для страницы справочника скопируйте в него шаблон и заполните.
  5. Отправьте pull request, как при правке.
  1. Откройте в репозитории папку src/assets/.
  2. Нажмите Add file → Upload files и загрузите картинку. Имя файла — латиницей и по смыслу, например freezezone_settings.png.
  3. Вставьте её в текст путём от страницы:
    • со страницы справочника (reference/…) — ![Что на скриншоте](../../../assets/freezezone_settings.png);
    • с остальных страниц — ![Что на скриншоте](../../assets/freezezone_settings.png).

Страницы в en/ лежат на уровень глубже, поэтому им нужен на один ../ больше.

При сборке картинка сжимается сама, а на сайте по щелчку открывается в полном размере.

Напишите в Discord или создайте Issue: что неправильно, чего не хватает, какой вопрос остался. Правку внесут за вас.

  • Справочник — одна страница на одну вещь, которую настраивает картодел: компонент, сущность, настройка. Образец: Группы и слоты.
  • Частые ошибки — «сделал так, а оно не работает, потому что…». Сюда идёт всё, о чём спрашивают в Discord больше одного раза.
  1. Основной язык — русский. Английская страница — перевод русской, по тому же пути в папке en/. Поправили русскую — английскую можно не трогать: на ней сама появится плашка «перевод может быть устаревшим», а npm run i18n покажет все отставшие страницы.
  2. Пишите просто и по делу — как в хорошем техническом руководстве. Без сленга и шуток, но и без канцелярита: не «данный компонент осуществляет блокировку», а «компонент блокирует». К читателю обращайтесь на «вы», в инструкциях используйте повелительное наклонение: «поставьте», «включите».
  3. Поля называйте так же, как редактор, и добавляйте рядом имя из кода: «Countdown Seconds (m_CountdownSeconds)». По такой подписи читатель найдёт поле в Workbench, а не будет гадать, что вы перевели.
  4. Показывайте, а не пересказывайте. Скриншот, на котором обведено нужное поле, заменяет абзац описания.
  5. Называйте версию мода, если поведение появилось или изменилось в конкретной версии.
  6. Не уверены — пишите всё равно, но поставьте блок «Требует проверки». Неполная страница полезнее пустого места.
  7. Объясняйте правки чужого текста. Нашли ошибку — исправьте и напишите в pull request, что и почему изменили.

Страницы пишутся в Markdown. Кроме обычных заголовков, списков и таблиц пригодятся:

Ссылка на другую страницу — адрес от корня сайта со слешем на конце: [Зоны](/reference/zones/).

Путь к префабу или конфигу — ссылкой, которая открывает файл в Workbench: ~EchoLobby для файлов мода, ~ArmaReforger для ванильных:

[`Prefabs/Zones/EH_Polyline_KillZone.et`](enfusion://ResourceManager/~EchoLobby:Prefabs/Zones/EH_Polyline_KillZone.et)

Выделенные блоки:

:::note
Дополнительная информация.
:::
:::tip
Полезный совет.
:::
:::caution[Требует проверки]
Что именно нужно проверить.
:::
:::danger
То, что может сломать миссию.
:::

Порядок в меню задаётся в начале файла:

---
title: Название
description: Одно предложение о странице
sidebar:
order: 5
---