Skip to main content

Правила написания руководства

Общие рекомендации​

  • Если раздел описывает конкретный раздел навигатора, то имя MD-файла совпадает с именем ID навигатора
  • Если раздел не связан с навигатором, то в качестве имени MD-файла выбирается любое доступное имя, соответствующее описанию раздела
  • Текст должен находиться в зоне видимости экрана. Не допускается уход текста за границы экрана, так как это нарушает читаемость текста. Форматирование текста возможно вручную по знакам препинания или пробелу, настройками в IDEA на автоматический перенос или по CTRL+ALT+L
  • Обильное наличие скриншотов — не самоцель: есть описание, можно вызвать реальное отображение и посмотреть, но каждому разделу как минимум должен соответствовать один рисунок, чтобы представлять общий вид. Важным является детальное описание функционала
  • Скриншоты сохраняются в папку img, расположенную рядом с MD-файлами. При ссылке на скриншоты пишем относительный путь img/имя_файла.png
  • Скриншоты именуются по имени файла MD с добавлением порядкового номера в конце имени. Номера рисунков соответствуют номерам скриншота
  • При описании разделов не используем admonitions вида :::. Вместо них применяем блоки <tip>, <info>, <warning> или пишем жирным: примечание, см. также, внимание и так далее. Это будет гарантировать беспроблемную конвертацию в другие форматы, например, PDF. Для примера:
  • Совет 1
  • Совет 2
  • Дополнительная информация
  • Примечание
  • Важно
  • Требует внимания

Всегда все пункты идут как список, даже если элементов в списке один

  • Подпись картинки — курсив, для отделения наименования скриншота от текста, идущего за наименованием

  • Если описание разделов неполное и что-либо надо доделать, то в нужном месте доработки разработчиком пишется TODO:

  • Если описание разделов неполное и пока доделать не представляется возможным, то в конце раздела помещается фраза: Содержание раздела находится в разработке

  • Если описание содержит ошибки, которые были обнаружены при проверке текста, то проверяющий ставит FIXME, что надо исправить

Соглашения по оформлению текста​

  • Буква ё в тексте не используется: пишем «приемка», «определенный», «ее»
  • В качестве тире используется длинное тире —, дефис - применяется только внутри слов
  • Пути меню записываются жирным с длинным тире в качестве разделителя: Справочники — Товары — Товары
  • Названия элементов интерфейса (кнопки, вкладки, флажки, колонки) выделяются жирным и приводятся ровно так, как они написаны на экране
  • Подпись рисунка оформляется единообразно: _Рис. N Название_ — точка после номера рисунка не ставится
  • Элемент списка с определением оформляется как **Название элемента** — что делает. с точкой в конце

Рекомендации при создании разделов​

На примере справочника
Справочник предназначен или определяет ... желательно пояснить в общих чертах
Справочник доступен из меню такой-то (рис. 1)
Справочник может как импортироваться из внешней системы, так и создаваться и редактироваться в LSF WMS. Если такое есть

Форма отображения справочника​

Ссылка на рисунок
Рис. 1 Форма отображения справочника
Дополнительные сведения о форме, например, фильтры, кнопка Печать

Форма редактирования справочника​

Ссылка на рисунок
Рис. 2 Форма редактирования справочника

Вкладка Название вкладки 1​

Краткое описание вкладки: отображает, предназначена и т.д.

Ссылка на рисунок
Рис. 3 Вкладка Название вкладки 1

Более детальное описание элементов вкладки

Вкладка Название вкладки N​

Краткое описание вкладки: отображает, предназначена и т.д.

Ссылка на рисунок
Рис. N Вкладка Название вкладки N

Более детальное описание элементов вкладки

Шаблоны фраз и слов​

  • При описании дерева — поле Родитель: родительская категория, на один уровень выше текущей в иерархии
  • Описание фильтров формы — фильтр, включающий отображение строк
  • Объем или кубатура — м³

Блок INFO​

Печать доступна из меню:

  • Справочники — Товары — Товары с выбором перед печатью шаблона этикетки из списка закрепленных за товарной категорией (флажок Вкл.) этикеток, по текущей отдельной позиции
  • Печать — Товар — Печать этикеток товара — печать этикетки по умолчанию (флажок Умолч.) для всех отмеченных или только текущей товарной позиции

Управление шаблонами:

  • Управление шаблонами доступно из меню Печать — Товар — Шаблон этикеток товара
  • Подробнее о печати см. в разделе Подсистема печати

Линии внутри текста​

Текст 1

Текст 2

В блоке Title добавление разделов​

toc_max_heading_level: 4

Last updated on