Skip to content

DOCUMENTATION.md

Latest commit

 

History

History
109 lines (69 loc) · 6.91 KB

DOCUMENTATION.md

File metadata and controls

109 lines (69 loc) · 6.91 KB

Правило документации Neoxider

Единый стандарт для всех .md в Assets/Neoxider/Docs и корневых README. Цель: быстрый ответ «что это и как использовать» в начале каждого файла, единый стиль.

1. Язык и тон

  • Язык: русский.
  • Тон: сухо, по делу. Без маркетинговых фраз и очевидных пояснений («без кода», «no-code» не использовать как основной ярлык).
  • Термины: скрипт/класс/компонент — по контексту; путь к файлу — относительно Assets/Neoxider/Scripts или полный.

2. Два типа документов

2.1. Документ по скрипту/компоненту (один .md на класс или тесно связанную группу)

Обязательное начало — сразу после заголовка # ИмяКласса:

# ИмяКласса

**Что это:** [1–2 предложения: тип (MonoBehaviour/ScriptableObject/класс), назначение, путь к файлу, при необходимости пространство имён.]

**Как использовать:**
1. [Шаг 1.]
2. [Шаг 2.]
…

---

После --- идут секции по необходимости: Поля, Методы, События, Примеры, См. также.

  • В Что это обязательно: что за сущность, для чего, путь к .cs (можно коротко: Scripts/Quest/QuestConfig.cs).
  • В Как использовать — конкретные шаги (добавить на объект, назначить поле, вызвать метод, подписаться на событие). Если документ описывает только API — достаточно краткого «Получить через X, вызвать Y».

2.2. README раздела/модуля (оглавление и описание раздела)

Обязательное начало:

# Название модуля

**Что это:** [1–2 предложения: какой раздел/модуль, что в него входит, где лежат скрипты.]

**Оглавление:** [Таблица или список ссылок на документы раздела. При необходимости — «Как с этим работать» в 2–3 пунктах.]

---

Дальше — подразделы (Поток данных, Структура кода, Демо-сцены и т.д.) по необходимости.

3. Структура секций (документ по скрипту)

После блока «Что это» / «Как использовать» и разделителя ---:

Секция Содержание
Поля Таблица: имя поля, тип, назначение. Группировать по Header при необходимости.
Методы Таблица или список: сигнатура, возврат, краткое описание.
События UnityEvent и C# events: когда вызываются, параметры.
Примеры Минимальный код или сценарий использования.
См. также Ссылки на связанные документы.

Заголовки секций — ## Поля, ## Методы и т.д. Подзаголовки — ### … при необходимости.

4. Именование файлов и заголовков

  • Файл документа по скрипту: ИмяКласса.md или осмысленное короткое имя (например, QuestBridge.md для двух классов).
  • Заголовок H1: # ИмяКласса или краткое название (например, # Quest NoCode Action).
  • README раздела: README.md, заголовок # Название модуля или # Название — краткое описание.

5. Навигация и ссылки

  • Корневой индекс: Docs/README.md — точка входа в документацию; ссылки на все модули и подмодули Tools.
  • README модуля (в подпапке Docs): после блока «Что это» — строка Навигация: с ссылкой на родительский README, например: **Навигация:** [← К Docs](../README.md) · оглавление — …. Затем оглавление (таблица или список ссылок на документы раздела).
  • Ссылки в таблице Docs/README: везде указывать явный путь к README подмодуля, например [Tools/Inventory/README.md](./Tools/Inventory/README.md), а не [Tools/Inventory](./Tools/Inventory).
  • В конце документа по скрипту при необходимости — блок См. также со ссылками на связанные .md.
  • В тексте ссылки в формате [текст](path/to/File.md).

6. Проверка при добавлении/правке .md

  • В начале каждого .md есть блок Что это (и для скрипта — Как использовать или эквивалент).
  • Путь к скрипту указан в Что это.
  • Стиль совпадает с остальной документацией (русский, сухо, без лишних вводных).
  • README модуля содержит Оглавление со ссылками.

7. Приведение существующих файлов

При правке любого .md проверьте:

  • в начале есть блок Что это (и для скрипта — Как использовать или Оглавление для README);
  • путь к скрипту указан в Что это;
  • стиль сухой, без лишних вводных.

Список документов, уже приведённых к правилу, можно получить поиском по фразе «Что это» в папке Docs. Остальные файлы дорабатываются по мере редактирования или массово по тому же шаблону.

Подробнее об организации папок и процессе обновления — см. DOCUMENTATION_GUIDELINES.md.