Правила оформления документации Planiqum¶

Этот документ описывает правила оформления пользовательской и администраторской документации Planiqum в формате Markdown для сайта, собираемого на MkDocs Material.

См. также "Промпт для ИИ ассистента"

1. Общие принципы¶

Язык: русский.
Стиль: деловой, спокойный, без бюрократизмов и сленга.
Обращение: «вы» / безличные формулировки («пользователь может…», «администратор настраивает…»).
Каждый раздел документации отвечает на понятный вопрос:
что это такое?
для кого это?
как этим пользоваться на практике?

Приоритет: ясность и однозначность важнее «литературности».

2. Структура страницы¶

2.1. Заголовок страницы¶

Страница начинается с заголовка уровня # (H1).
Название должно быть понятно без контекста:

Документация Planiqum¶

Инструкция администратора¶

Инструкция пользователя¶

Работа с данными в дашбордах Planiqum¶

Модуль интегрированного бизнес-планирования (IBP-шаблон)¶

Допускается использование HTML в заголовке (например, для логотипа):

Документация Planiqum

2.2. Вступительный блок¶

Сразу после заголовка — 1–3 абзаца, которые:

кратко описывают назначение раздела;
поясняют, для кого он (роль, тип пользователя);
при необходимости дают ссылки на базовые концепции.

Пример:

Инструкция администратора описывает настройки, которые выполняет администратор системы Planiqum: управление пользователями и группами, настройка прав доступа, параметров и системных модулей.

2.3. Основные разделы (H2, H3)¶

Основные смысловые блоки — заголовки ## (H2).
Внутри них — при необходимости заголовки ### (H3).

Примеры типовых заголовков:

Назначение и роль¶

Начало работы¶

Права и группы¶

Структура рабочей области¶

Описание и позиционирование¶

Импорт и ведение исходных данных¶

Планирование спроса¶

Планирование производства¶

Одна секция — одна тема. Если в секции больше 2–3 подтем, выносим их в ###.

3. Описание сущностей и терминов¶

3.1. Формат определения¶

Для ключевых сущностей используем шаблон:

Термин (синонимы "…") — краткое определение в одном–двух предложениях.

Примеры:

Права (синоним "Разрешения") — элементарные действия, которые пользователь может выполнять в системе, например просмотр, редактирование или удаление данных.

Модуль IBP (синонимы "Надстройка IBP", "IBP-шаблон") — надстройка над платформой Planiqum, поддерживающая полный цикл интегрированного бизнес-планирования.

3.2. Термины интерфейса¶

Названия полей, параметров, флагов и значений интерфейса — в моноширинном формате:

Поле Scenario определяет сценарий планирования.

Если термин важен и часто используется — выделяем жирным при первом упоминании.

4. Списки, примеры, пояснения¶

4.1. Маркированные списки¶

Используем для:

преимуществ;
функций;
шагов процесса;
ограничений и правил.

Пример:

Использование IBP-шаблона даёт следующие преимущества:

Быстрое прототипирование процессов интегрированного планирования.
Типовой функционал с широкими возможностями настройки.
Использование лучших практик планирования спроса и производства.

4.2. Нумерованные списки¶

Используем для пошаговых инструкций:

Чтобы изменить значение в ячейке:

Дважды щёлкните по ячейке.
Введите новое значение.
Нажмите Enter для подтверждения.

4.3. Примеры и рекомендации¶

Для примеров и пояснений используем блоки цитирования:

Например, для выделения функциональной роли и области можно использовать следующую схему именования:

Менеджер по продажам региона ЮГ

Менеджер по продажам региона СИБИРЬ

5. Ссылки и навигация¶

5.1. Внутренние ссылки¶

Используем относительные пути, соответствующие структуре docs_dir: md в mkdocs.yml:

Инструкция администратора Инструкция пользователя Процесс IBP

При ссылке на конкретный подзаголовок используем якоря:

либо автоматически (по тексту заголовка),
либо задавая id явно:

Права ¶

См. также раздел Права.

5.2. Внешние ссылки и почта¶

Сайт Planiqum Написать в поддержку

(адреса подставляются реальные, по договорённости в команде).

6. Картинки и файлы¶

6.1. Картинки¶

Путь задаём относительно текущего .md:

Правила:

имя файла — латиницей, без пробелов: admin_groups_permissions.png;
в квадратных скобках — краткий alt-текст (что изображено);
в кавычках — подпись при наведении.

При необходимости управления размером/выравниванием допускается HTML:

6.2. PDF и другие вложения¶

PDF-файлы кладём в подкаталог, например documents, и ссылаемся через HTML, чтобы открыть в новой вкладке:

«Руководство пользователя платформы Planiqum»

7. Специфика разных типов разделов¶

7.1. Главная страница документации¶

Содержит:

краткое описание Planiqum;
указание текущей версии;
ссылки на основные блоки:
Инструкция пользователя,
Инструкция администратора,
Надстройка IBP,
Документация для разработчиков.

Рекомендуемая структура:

Документация Planiqum¶

Ваша версия системы: 0.x.x (релиз YYYY-MM-DD) Список поддерживаемых версий и описание изменений — в разделе История изменений.

Основные разделы¶

(пути и названия подстраиваются под фактическую структуру mkdocs.yml.)

7.2. Инструкция администратора¶

Фокус раздела:

назначение роли администратора;
описание панели администратора;
управление пользователями и группами;
настройка прав;
параметры, интеграции, логи.

Каждая страница должна:

описывать цель настройки (что меняем и зачем);
показывать основные элементы интерфейса;
приводить рекомендации по настройке (best practices).

7.3. Инструкция пользователя¶

Фокус:

сценарии работы в дашбордах;
базовые операции (просмотр, фильтрация, сортировка, корректировка);
объяснение ключевых понятий (сценарии, слои данных, периоды, иерархии).

Страницы:

говорят на языке конечного пользователя;
ссылаются на админские разделы только при необходимости (без технических деталей, если их можно спрятать под ссылку).

7.4. Надстройка IBP¶

Для страниц, описывающих IBP-шаблон:

чётко разделяем:
концепцию процесса IBP (что планируем, какие уровни, какие горизонты, какие роли);
реализацию в Planiqum (структура форм, слоёв данных, сценариев, параметров).
объясняем, какие роли вовлечены и в какой части процесса.

8. Стиль текста¶

Избегаем очень длинных предложений (обычно 1–2 мыслительных действия в одном предложении).
Не злоупотребляем вводными конструкциями («следует отметить», «как известно»).
Жирным выделяем:
ключевые понятия;
важные предупреждения;
названия ролей и модулей при первом упоминании.
Курсивом выделяем:
пояснения;
мягкие акценты;
части примеров.
Моноширинным выделяем:
имена полей;
названия внутренних параметров;
кодовые значения.

9. Контрольный список перед коммитом¶

Перед тем как коммитить изменения в документацию:

Страница начинается с # и короткого понятного заголовка.
Есть короткое вступление: кто читатель и о чём этот раздел.
Структура оформлена через ## / ###, нет «простыни» из текста.
Термины и сущности имеют явные определения там, где это необходимо.
Списки используются там, где перечисляются функции, шаги или правила.
Ссылки рабочие и относительные, пути соответствуют структуре каталога md/.
Картинки и PDF-файлы лежат в правильных папках, имена файлов без пробелов и кириллицы.
Орфография проверена (spell checker не подсвечивает лишних ошибок).
Файл успешно собирается локально через mkdocs serve (нет ошибок в mkdocs.yml и навигации).

Важно: описанные настройки и сценарии могут отличаться в вашей инсталляции Planiqum
За уточнениями и методологической поддержкой обращайтесь в компанию ЮНИК СОФТ