Правила оформления статей и компоненты VirtualPos

Руководство для авторов справки VirtualPos: как строить статью, как её оформлять и какие визуальные компоненты можно использовать. Компоненты дают шаблон virtualpos и плагины vpmeta и wrap; большинство из них вставляется кнопкой «Компоненты статьи VirtualPos» на панели редактора. Короткая шпаргалка с образцом — статья Компоненты статей VirtualPos, общий синтаксис DokuWiki — Formatting Syntax. Образец готовой статьи — Заявки на пополнение запасов, образец описания API — Customer. Клиенты.

Справка пользователя лежит в пространстве имён hc:, далее — раздел и статья: hc:<раздел>:<статья>. Например, hc:purchase:requisition — статья «Заявки на пополнение запасов» раздела «Закупки».

Устаревший функционал не удаляют, а переносят в нужный раздел и помечают в начале статьи блоком «Этот функционал более не поддерживается» (компонент «Внимание», см. ниже).

Все статьи строятся по одной схеме:

~~ICON:assignment_add~~
~~PATH:Закупки → Заявки на пополнение~~

====== Заявки на пополнение запасов ======

Заявки формируют потребность в товаре и служат основой для заказов поставщикам.

===== Как это работает =====
...

===== Связанные разделы =====

<WRAP related>
  * [[hc:purchase:purchase_order|Заказы поставщикам]] Заказы, созданные на основе заявок
</WRAP>

Заголовок раздела отвечает на вопрос читателя: «Как создать заявку», «Статусы заявки», «Права доступа». Не заканчивайте заголовки точкой.

• Язык — русский. Пишите от второго лица во множественном числе повелительного наклонения: «Нажмите», «Выберите», «Укажите». Не используйте разговорные обороты и слова «просто», «легко».
• Названия интерфейса — кнопки, пункты меню, поля, вкладки пишите жирным шрифтом: Создать, Настройки. Пункты меню соединяйте стрелкой: Закупки → Заявки на пополнение.
• Термины — во всей справке одно и то же слово для одного понятия: «точка продаж», «поступление», «остаток». Не смешивайте синонимы.
• Коды, значения, параметры — моноширинным шрифтом (двойные апострофы): NEW, console.requisition.confirm, apikey.
• Кавычки — «ёлочки» для названий статусов, документов и цитат.
• Идентификаторы — в описаниях полей вместо «номер» для ид записи пишите «ид»: «Ид клиента», «Ид точки продаж».
• Списки — маркированные для перечислений, нумерованные только для последовательных действий. Каждый пункт — законченная мысль.
• Длина — один абзац — одна мысль, не длиннее пяти-шести строк. Длинные инструкции разбивайте на шаги.
• Не дублируйте общее знание: вместо повторения инструкции дайте ссылку на статью, где она описана.

Ссылки на статьи всегда пишите с названием после | и полным именем страницы (hc:раздел:статья). Ссылки на удалённые или несуществующие страницы отображаются красным: проверяйте их перед публикацией.

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

~~ICON:assignment_add~~
~~PATH:Закупки → Заявки на пополнение~~

Иконку задавайте у каждой статьи: разным статьям — разные иконки, по смыслу. Путь указывайте, если функция есть в панели управления или на кассе.

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

Основная цель процесса — закупать то, что нужно, и столько, сколько нужно.

> Основная цель процесса — закупать то, что нужно, и столько, сколько нужно.

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

<WRAP steps>
  - **Создание** Кладовщик создаёт заявку и добавляет товары.
  - **Согласование** Руководитель согласует количества.
  - **Заказы** Закупщик создаёт заказы на основе заявок.
</WRAP>

Подробная пошаговая инструкция. Нумерация не сбивается, даже если между шагами вставлены скриншоты.

1. Отметьте нужные строки.
2. Выберите поставщика.

1. Нажмите «Создать заказ».

<WRAP procedure>
  - Отметьте нужные строки.
  - Выберите поставщика.

{{:hc:purchase:pasted:20260325-163311.png?400|Выбор строк и поставщика}}

  - Нажмите «Создать заказ».
</WRAP>

Один шаг — одно действие. Результат шага можно описать в следующей строке или в блоке «Результат».

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

{{:hc:purchase:pasted:20260320-184811.png?580|Форма создания заявки}}

Правила для скриншотов: снимайте только нужную часть окна; не показывайте реальные персональные данные, ключи доступа и пароли; подписывайте каждый скриншот.

Список «название — описание» вместо таблицы: для полей формы, параметров, настроек. Слева название жирным, справа пояснение.

<WRAP props>
| **Склад** | Склад, для которого формируется потребность |
| **Статус** | Текущий статус заявки |
</WRAP>

Каждая строка — одна пара, разделители | в начале и в конце строки. Внутри ячейки можно использовать форматирование и код.

Значения параметра и что происходит при каждом из них. Название параметра — курсивом, значение — жирным, пояснение — после него.

<WRAP cards>
  * //Заполнить автоматически// **Да** Система рассчитает потребность сама.
  * //Заполнить автоматически// **Нет** Закупщик наполняет заявку вручную.
</WRAP>

Метка статуса документа. Цвет соответствует смыслу: серый — начальный, жёлтый — требует внимания, синий — промежуточный, зелёный — завершён.

Новая На согласовании Подбор поставщиков Закрыта

<wrap status>Новая</wrap>
<wrap status warning>На согласовании</wrap>
<wrap status info>Подбор поставщиков</wrap>
<wrap status success>Закрыта</wrap>

Порядок переходов документа. Стрелки — символ →.

<WRAP flow>
<wrap status>Новая</wrap> → <wrap status warning>На согласовании</wrap> → <wrap status success>Закрыта</wrap>
</WRAP>

Что делает каждая кнопка документа и в какой статус он переходит. Первая строка пары — название действия и статус, вторая — описание; она заканчивается двумя ||. Описание можно не писать.

<WRAP actions>
| **«Утвердить»** | <wrap status info>Подбор поставщиков</wrap> |
| Требует права ''console.requisition.confirm''. ||
| **«Вернуть на доработку»** | <wrap status>Новая</wrap> |
| Заявка возвращается к формированию потребности. ||
</WRAP>

Цветные блоки для важных замечаний. Начинайте текст жирным словом-меткой. Не злоупотребляйте: не больше одного-двух блоков на раздел.

<WRAP info>
**Подсказка.** Полезная информация по теме.
</WRAP>

<WRAP tip> ... </WRAP>
<WRAP help> ... </WRAP>
<WRAP success> ... </WRAP>
<WRAP important> ... </WRAP>
<WRAP alert> ... </WRAP>

<WRAP permission>
Требует права ''console.requisition.complete''.
</WRAP>

<WRAP todo> ... </WRAP>
<WRAP download> ... </WRAP>

Блоку можно добавить слова center round и ширину в процентах — он будет по центру страницы и уже основного текста. Так оформляют, например, ссылку на скачивание.

<WRAP center round download 60%>
**Скачать программу**: [[https://example.com/setup.zip]]
</WRAP>

Блок box выводит текст в нейтральной рамке: подходит для команд и коротких значений.

<WRAP center round box 60%>
php -S 0.0.0.0:8080 -t wwwroot
</WRAP>

Слова внутри строки можно выделить фоном: <wrap hi>текст</wrap> — важное слово, <wrap info>…</wrap>, <wrap important>…</wrap>, <wrap alert>…</wrap>, <wrap tip>…</wrap>: информация внимание запрет совет. Используйте редко, только для одного-двух слов.

Две колонки рядом: для сопоставления текста и картинки или двух списков. На узких экранах колонки встают друг под друга.

<WRAP group>
<WRAP half column>
  * Первая колонка
</WRAP>

<WRAP half column>
  * Вторая колонка
</WRAP>
</WRAP>

Блок <WRAP col2> делит на две колонки содержимое одного блока — используйте его, когда нужно расположить текст и рядом скриншот.

Обычные таблицы DokuWiki. Заголовки колонок — между ^, ячейки — между |. Код в ячейках (NEW) выводится мелким моноширинным шрифтом. В ячейку можно поместить статус.

^ Статус ^ Код ^ Описание ^
| <wrap status>Новая</wrap> | ''NEW'' | Черновик заявки |
| <wrap status success>Закрыта</wrap> | ''COMPLETED'' | Заявка выполнена |

Таблицу используйте, когда у данных несколько колонок. Пары «название — описание» оформляйте компонентом «Поля и описания».

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

{"success": 1, "id": "21"}

<root><success>1</success></root>

<code json>
{"success": 1, "id": "21"}
</code>

<code xml>
<root><success>1</success></root>
</code>

<code>
GET https://[компания].myvirtualpos.ru/api/customer?apikey=MySecret
</code>

Поддерживаются json, xml, bash, sql, php и другие языки; без указания языка блок показывается без подсветки. В примерах используйте вымышленные данные, а ключ доступа заменяйте на MySecret.

Карточки со ссылками на смежные статьи в конце статьи. Строка: ссылка с названием, затем через пробел — короткое пояснение. Иконка карточки берётся из ~~ICON~~ целевой статьи.

<WRAP related>
  * [[hc:purchase:purchase_order|Заказы поставщикам]] Заказы, созданные на основе заявок
  * [[hc:stock:inflow|Приёмка товара]] Оформление поступления товара на склад
</WRAP>

Статьи раздела hc:api строятся по единому плану:

• Есть ~~ICON~~ и, если применимо, ~~PATH~~.
• Один заголовок первого уровня, разделы — второго, лид написан.
• Все ссылки ведут на существующие страницы (не красные).
• Все скриншоты подписаны, без персональных данных, ключей и паролей.
• Названия элементов интерфейса — жирным, коды и значения — моноширинным.
• Блоки <WRAP> и <code> закрыты.
• В конце — «Связанные разделы».
• Статья открыта в браузере и проверена глазами, в том числе в узком окне.