Использование ИИ при подготовке документации Planiqum¶

В этом документе описаны готовые промпты для использования ИИ (например, ChatGPT) при написании и редактировании документации Planiqum.

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

копировать промпт целиком;
в нужных местах дописывать конкретную задачу (про какой раздел пишем);
всегда проверять, править и приводить результат к правилам из раздела «Правила оформления документации Planiqum».

1. Базовый промпт для нового раздела¶

Используйте этот промпт, когда нужно написать новую страницу документации.

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

Соблюдай следующие правила оформления:

Язык и тон

Пиши по-русски, деловым, но понятным языком.

Избегай бюрократизмов, лишних вводных («следует отметить» и т.п.) и сленга.

Обращайся к читателю на «вы» или используй нейтральные формулировки («пользователь может…»).

Структура

В начале — заголовок уровня H1 (#), отражающий суть раздела.

Далее 1–3 абзаца вступления: кому раздел, о чём он, какую задачу решает.

Основная часть — блоки с заголовками ##, внутри при необходимости ###.

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

Термины и определения

Для ключевых сущностей используй формат: **Термин** (синонимы "…") — краткое определение.

Названия полей и параметров интерфейса выделяй моноширинным шрифтом: `field_name`.

Списки и примеры

Используй маркеры для перечислений (функции, преимущества, шаги).

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

Для примеров используй блоки цитирования >; внутри можно добавлять списки.

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

Используй относительные ссылки на другие разделы, например: [Инструкция администратора](../admin/admin_index.md).

При ссылке на фрагмент внутри страницы можно использовать якорь #anchor.

Картинки и файлы

Если нужны скриншоты, используй синтаксис Markdown: ![Краткое описание](../images/file_name.png "Подпись").

Придумай осмысленные подписи, но не вставляй реальные пути к файлам, если они тебе неизвестны — лучше оставь комментарий-подсказку.

Стиль текста

Выделяй важные слова и понятия жирным.

Избегай слишком длинных предложений (обычно до 2 мыслей в одном предложении).

Не дублируй одно и то же разными словами.

Вывод

В ответе выдай только Markdown-текст раздела, без пояснений и метакомментариев.

Теперь, исходя из этого, напиши раздел документации Planiqum про:
[КРАТКО ОПИШИ ТЕМУ РАЗДЕЛА]
Для контекста: [ДОБАВЬ, К КАКОМУ РАЗДЕЛУ ОТНОСИТСЯ (ПОЛЬЗОВАТЕЛИ / АДМИНИСТРАТОРЫ / IBP)].

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

2. Промпт для переработки существующего раздела¶

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

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

Правила оформления:

Структура: # заголовок → краткое вступление → блоки ## → при необходимости ###.

Язык: русский, деловой, без бюрократии и сленга.

Термины: явные определения, формат **Термин** — определение.

Списки для перечислений и шагов; примеры в блоках цитирования.

Ссылки — относительные, формат Markdown.

Названия полей и параметров интерфейса — в формате `field_name`.

Задачи:

Сохранить все важные смысловые части текста.

Упростить формулировки, уменьшить длину предложений.

Добавить заголовки ## / ###, если текст пока не структурирован.

Привести оформление к единому стилю Planiqum (как описано выше).

В ответе:

выдай только переработанный Markdown-текст;

не добавляй комментариев и пояснений;

не используй никаких служебных меток/сносок.

Вот исходный текст раздела, который нужно переработать:
[ВСТАВЬ СЮДА ТЕКУЩЕЕ СОДЕРЖИМОЕ ФАЙЛА .md]

3. Промпт для вычитки и улучшения текста¶

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

убрать шероховатости;
выровнять стиль;
поймать мелкие неточности.

Ты выступаешь в роли редактора документации системы Planiqum.

У тебя есть раздел документации в формате Markdown.
Нужно:

Проверить стиль и ясность формулировок.

Упростить фразы, где это возможно, не теряя смысла.

Сохранить структуру (#, ##, ###, списки, ссылки, форматирование).

Не менять технический смысл, термины и ссылки.

Важно:

Не вводи новые функции, параметры или поведение, которых нет в исходном тексте.

Не меняй структуру раздела радикально — только улучшай формулировки и оформление.

В ответе выдай только обновлённый Markdown-текст без комментариев.

Вот текст для вычитки:
[ВСТАВЬ СЮДА СУЩЕСТВУЮЩИЙ ТЕКСТ]

4. Как использовать эти промпты в команде¶

Рекомендуемый процесс для авторов:

Новый раздел
Сначала продумать структуру (какие блоки нужны).
Использовать базовый промпт для генерации черновика.
Проверить и доработать текст вручную по правилам из planiqum_docs_rules.md.
Обновление существующего раздела
Вставить текущий текст в промпт для переработки.
Проверить результат и вручную откорректировать спорные моменты.
Финальная вычитка
Использовать промпт для вычитки как дополнительную проверку.
Обязательно проверить техническую точность и актуальность самостоятельно.

В любом случае последнее слово остаётся за автором/редактором, а не за ИИ.
Все изменения проходят через Git (ветка update_doc или другая профильная ветка для документации) и проверяются на сборку с помощью mkdocs serve / mkdocs build.

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