Гайд автора Wiki SKIF.PRO

1. Зачем мы это меняем

Нынешняя wiki wiki.skif.pro писалась без единых правил. Каждый автор оформлял по-своему. Сейчас в ней такое количество статей, что несогласованность стала проблемой и для пользователей, и для нас.

Что сейчас не так — на конкретных примерах

Проблема 1. Мегастраницы вместо отдельных статей

Открой страницу «Отчёты». Это один файл с тремя заголовками первого уровня и более чем 50 подзаголовками. По сути — вся документация по отчётам в одном бесконечном свитке. Пользователь не может скинуть клиенту ссылку «на отчёт по топливу» — только на середину гигантского документа.

Аналогично страница «Объекты» — три заголовка первого уровня, 16+ подзаголовков, 82 скриншота в одном файле.

Проблема 2. Каждый автор пишет в своём стиле

На странице «Объекты» рядом стоят подзаголовки:

• «Создание датчиков» (множественное число, без двоеточия)
• «Удаление датчика:» (единственное число, с двоеточием)
• «Тарировка датчика» (просто существительное)
• «Создание/Редактирование объекта» (два действия в одном)

Это всё в одной статье. У читателя — ощущение, что писали разные люди, и нет общей логики.

Проблема 3. Параметры формы не оформлены как справочник

На странице «Объекты» — 82 скриншота и только 2 таблицы. Описания параметров рассыпаны прозой между картинками. Чтобы найти, что значит конкретное поле, нужно пролистать половину страницы и читать абзацами. У Wialon такие параметры — в одной таблице «Параметр | Описание».

Проблема 4. Описание сущности и инструкции разбросаны

Что такое геозона? Когда её создают? Где она применяется? Сейчас эти вопросы освещены в трёх-четырёх разных местах wiki, и пользователю приходится складывать понимание из обрывков.

Что меняется

Берём за основу структуру wiki Wialon — это лидер рынка мониторинга транспорта, у них wiki проверена годами и тысячами клиентов. Каждая сущность (геозона, объект, поле, отчёт) получает отдельную папку с 4–5 файлами:

Сравни сам: наша текущая страница «Геозоны» (одна мегастраница с двумя заголовками первого уровня) и геозоны у Wialon (обзор + 4 отдельных файла, у каждого свой URL и оглавление).

Что это даст тебе как автору

• Меньше думать «куда положить». Структура папки сущности стандартная — открыл шаблон, заполнил. Не надо изобретать раскладку каждой статьи.
• Меньше переписывать. Свойства лежат в одном месте. Добавилось новое поле в форме — правишь одну строку в одной таблице, а не разбросанный текст в трёх разных местах.
• Чёткие границы статьи. Знаешь, когда статья готова: есть первый абзац, есть таблица свойств, есть шаги создания. Не нужно гадать, что ещё дописать.
• Можно скидывать клиенту точную ссылку. «Создание геозон» — отдельный URL вместо «открой Геозоны и листай вниз».

2. Как начать в Obsidian

Практический алгоритм на 5 шагов — от пустого экрана до сохранённой статьи.

Шаг 1. Открой папку wiki в Obsidian

В левой панели Obsidian увидишь дерево папок. Найди корневую папку wiki. Внутри неё — папки разделов: Объекты, Геозоны, Отчёты, Агро-модуль и т.д.

Шаг 2. Найди папку нужной сущности

Решил написать про создание поля в Агро-модуле? Открой wiki → Агро-модуль → Поля. Внутри этой папки уже есть несколько файлов.

Если папки сущности нет — значит, эта сущность ещё не описана в wiki. Спроси в чате, есть ли план по ней, или создавай новую папку.

Шаг 3. Создай файл с правильным именем

Имя файла = заголовок статьи + расширение .md. Никаких «как», никаких вопросов.

Шаг 4. Напиши статью по шаблону

Минимальный шаблон любой статьи:

# Заголовок (тот же, что в имени файла)

Один абзац: какие права доступа нужны или что должно быть готово.

## Первый подзаголовок

Содержимое раздела.

## Второй подзаголовок

Содержимое раздела.

## Смотрите также

- [Соседняя статья](Соседняя статья.md)
- [Другая статья](../Другая папка/Другая статья.md)

Шаг 5. Сохрани файл

Нажми Ctrl+S (или Cmd+S на Mac). Статья сохранена в твоём Obsidian.

О том, как доставить изменения в общую wiki и запустить проверку — отдельная инструкция (она у твоего руководителя или в рабочем чате).

3. Что такое «сущность» в нашей wiki

Прежде чем писать — определись, какую сущность твоя статья описывает.

В SKIF.PRO пользователь работает с разными понятиями: объектами, геозонами, отчётами, уведомлениями, водителями. В этом гайде мы называем такие понятия сущностями. Каждая сущность получает отдельную папку в wiki и набор статей внутри.

Основные сущности SKIF.PRO

Что НЕ является сущностью

• Кнопка в интерфейсе (это деталь сущности)
• Настройка одного параметра (это строка в таблице «Свойства»)
• Сценарий использования (это раздел «Применение»)

4. Структура папки сущности

Каждая сущность = папка с 4–5 файлами + одна обзорная страница рядом.

Полный набор файлов

Какой набор для каких сущностей

Где «Редактирование» и «Удаление»?

В файле «Работа с {сущности}.md», как подзаголовки H2. НЕ в «Создание» и НЕ отдельными файлами.

Это логика Wialon: «Создание» — про сценарий «у меня нет сущности, я хочу её создать»; «Работа с» — про сценарий «у меня уже есть сущности, я хочу их использовать, изменять или удалять». Редактирование и удаление концептуально относятся ко второй группе.

5. Заголовок статьи

Wialon никогда не использует вопросительные заголовки. Никаких «Как создать…», «Что такое…», «Почему не работает…».

Формат заголовка

Заголовок строится по одной из трёх формул:

1. Отглагольное существительное + сущность: «Создание геозон», «Свойства объекта», «Применение отчётов»
2. «Работа с» + сущность в творительном падеже: «Работа с геозонами», «Работа с объектами»
3. Имя сущности целиком: «Геозоны», «Объект на карте» (для обзорных страниц)

Сравнение со старым стилем

Имя файла — то же, что заголовок в файле

Файл называется так же, как заголовок внутри. Создание геозон.md ↔ # Создание геозон. Никаких сокращений.

6. Первый абзац (лид)

У Wialon лид-абзац всегда содержит конкретику: какие права доступа нужны, что должно быть готово до того, как начать.

Что должно быть в лиде

• Какие права доступа нужны (роль, уровень доступа к ресурсу)
• Какие предусловия должны быть выполнены
• В каком модуле/разделе UI происходит действие

Эталонный лид от Wialon

Одно предложение. Конкретное название права. Никакой воды.

Что не так: три предложения, нет ни одного факта, который бы помог пользователю. Метакомментарий «в этой статье описано…» — обнуляющий.

Шаблон лида для разных типов страниц

Для «Создание …»

Для создания <сущности> необходимо право доступа <имя права> на <ресурс>.

Для «Свойства …»

Свойства <сущности> задаются при её создании и доступны для редактирования в форме <имя формы>.

Для «Работа с …»

Все <сущности> компании отображаются на вкладке <имя вкладки>. Здесь можно искать, фильтровать, экспортировать.

Для «Применение …»

<Сущность> используется в <модуль 1>, <модуль 2>, <модуль 3>. Ниже — как именно.

7. Подзаголовки внутри статьи

Подзаголовок в Markdown — это строка, начинающаяся с двух решёток ##. Используются для разделов внутри статьи.

Стандартный список подзаголовков

Если в твоей статье есть несколько разделов, выбирай их из этого списка и располагай в этом порядке:

1. Свойства — таблица параметров
2. Создание — нумерованные шаги
3. Редактирование — нумерованные шаги
4. Удаление — нумерованные шаги
5. Работа с — повседневные операции в интерфейсе
6. Группы — если у сущности есть группы
7. Применение — где используется в системе
8. Ограничения — лимиты, квоты
9. Смотрите также — ссылки на соседние статьи

Имя сущности в подзаголовке — обязательно

Можно ли использовать подзаголовки не из стандартного списка?

Да. Внутри файла «Создание геозон.md» Wialon добавляет такие подзаголовки:

• Этапы создания геозон (основные шаги)
• Очистка свойств геозоны (сброс параметров)
• Экспорт и импорт геозон
• Нанесение геозоны на карту

Это свободные подзаголовки — они описывают конкретные подсценарии. Так можно.

Правило: основные разделы — из стандартного списка, подсценарии — свободные.

Пустые подзаголовки запрещены

Если ты не готов написать содержимое раздела «Свойства геозон» — не ставь этот подзаголовок. Автоматическая проверка блокирует статьи с пустыми подзаголовками.

8. Пошаговые инструкции

В секциях «Создание», «Редактирование», «Удаление» — нумерованный список с короткими шагами в повелительном наклонении.

Эталон от Wialon

1. Нажмите на Создать на вкладке Геозоны.
2. Выберите тип геозоны: полигон, линия или круг.
3. Нанесите геозону на карту.
4. Введите название и описание.
5. Нажмите Сохранить.

Правила шагов

1. Нумерованный список (1. 2. 3.), не маркированный. Порядок важен.
2. Каждый шаг — одно предложение ≤25 слов. Длинный шаг = условные ветки = разбить на 2–3 шага.
3. Глагол в повелительном наклонении первым словом: «Нажмите», «Откройте», «Выберите», «Введите», «Заполните».
4. Названия UI-элементов жирным: кнопка Создать, вкладка Геозоны, поле Название.
5. Не вкладывай нумерованный список в нумерованный. Если внутри шага есть подпункты — маркированный список.

Подпункты в шаге

4. Заполните основные параметры:
   - Название — название поля в системе.
   - Тип — полигон или территория.
   - Группа — необязательно.

Длинный шаг — частая ошибка

Описание результата после шагов

Опиши, что должно получиться после выполнения шагов, обычным абзацем сразу после списка. БЕЗ отдельного подзаголовка «Результат».

Wialon не использует подзаголовок «Результат» — описание последствия либо встроено в последний шаг («Нажмите Сохранить, чтобы сохранить геозону»), либо идёт абзацем без заголовка после шагов.

9. Таблицы свойств

Любой набор параметров формы или опций экрана = таблица с двумя колонками. Wialon использует таблицы везде, где более 3–4 элементов.

Базовый формат

| Параметр | Описание |
|----------|----------|
| Название | Краткое имя геозоны в списке. До 200 символов. |
| Тип      | Полигон, линия или круг. |
| Группа   | Группа геозон, в которую попадёт новая. |
| Описание | Текстовое описание для других пользователей. |

Имя первой колонки — выбирай по контексту

Дополнительные колонки

Можно добавить колонки, если они полезны:

• По умолчанию — значение по умолчанию (если есть)
• Допустимые значения — список или диапазон для технических параметров
• Тип — тип данных (string, integer, boolean) — только для статей в разделе «API» и «Протоколы»

Когда таблица, а когда bullet-список?

Эталон от Wialon: таблица «Опция | Описание»

Откройте «Объект на карте» в Wialon — там сразу три таблицы «Опция | Описание». Это образец для всех справочных страниц.

Названия параметров — 1:1 с UI

Если в форме поле подписано «Сигнал GPS» — в таблице пиши «Сигнал GPS», не «GPS-сигнал», не «сигнал GPS».

10. Скриншоты

Wialon ставит 0–9 скриншотов на страницу — типично 1–6, максимум 9 встречен на «Создание геозон». На management-страницах он дополнительно использует inline-иконки UI — мелкие PNG прямо в строке текста рядом с именем кнопки (до 11 штук на странице, как в «Работа с геозонами»). Это два разных приёма, не путать. Подпись курсивом под скриншотом — наша внутренняя норма; у Wialon её нет, поясняет соседняя проза.

Где ставить скриншот

• В начале action-страницы — общий вид формы или экрана
• После ключевого шага — что должно получиться
• В «Свойствах» — общий вид формы со всеми параметрами
• В «Работа с» — общий вид списка и одна-две всплывающие подсказки. Не делай скрин на каждую кнопку — используй inline-иконки (см. ниже)

Inline-иконки UI

Когда в тексте упоминаешь кнопку панели инструментов или иконку-индикатор, ставь её мелкую PNG-иконку (≤3 КБ) прямо в строку текста рядом с именем. Так делает Wialon: «Открыть [icon] Редактировать» вместо отдельного скриншота для каждой кнопки.

• Используй для: кнопок панели действий списка (Редактировать, Копировать, Удалить), типов сущностей (полигон / линия / круг), индикаторов состояния (зелёный/красный маркер связи).
• Размер файла — <3 КБ. Если получается больше — это уже скриншот, а не иконка.
• Имя файла — латиницей по действию или сущности: edit.png, copy.png, polygon.png.
• Inline-иконкам подпись курсивом не нужна — они часть строки.

Как добавить

Кладёшь файл в wiki/Attachments/, ссылаешься так:

![Общий вид формы создания геозоны](Attachments/sozdanie-geozony-forma.png)

*Форма создания геозоны с обязательными полями*

Как называть файлы скриншотов

Имя файла — латиницей, через дефис, без пробелов и кириллицы. Шаблон: сущность-раздел-номер.png.

• ✓ geozona-sozdanie-1.png
• ✓ geozona-svojstva-forma.png
• ✗ Геозона создание 1.png (кириллица и пробелы)
• ✗ screenshot_2025-01-15.png (непонятно, что внутри)

Подпись обязательна

Под каждым скриншотом — курсивом одно предложение, что на нём показано. Это наша внутренняя норма для индексации и доступности (скринридерам нужен текст рядом, поиску — ключевые слова). У Wialon формальной подписи нет: поясняет соседний абзац прозы. Inline-иконкам подпись не нужна — они часть строки текста.

11. Ссылки на другие статьи

В конце статьи — секция «Смотрите также» (или «См. также») со ссылками на 2–5 смежных статей.

Формат секции

## Смотрите также

- [Создание геозон](Создание геозон.md)
- [Применение геозон в уведомлениях](../Уведомления/Применение геозон в уведомлениях.md)
- [Группы геозон](Группы геозон.md)

Что включать

• Другие статьи той же сущности (если осмысленно)
• Смотрите также сущности («Геозоны» ↔ «Уведомления», «Поле» ↔ «Геозона»)
• Концептуально близкие статьи

Что НЕ включать

• Хабы вышестоящих разделов (читатель найдёт их через хлебные крошки)
• Случайно показавшиеся «может пригодится» ссылки
• Более 5 ссылок (если их много — это сигнал, что статья сама хочет быть хабом)

Формат ссылки — только относительный путь к .md

12. Обзорная страница

Обзорная страница — это файл Геозоны.md рядом с папкой Геозоны/. Точка входа в сущность.

Что должно быть в обзорной странице

• Заголовок = имя сущности во множественном числе («Геозоны»)
• 1–3 абзаца описания: что это, зачем нужно
• Видео или скриншот общего вида (опционально)
• Список ссылок на все остальные статьи сущности

Эталонный пример

# Геозоны

Геозоны — виртуальные области на карте, при пересечении границ которых
система фиксирует событие. Используются для уведомлений о входе/выходе
транспорта, контроля маршрута, учёта времени на объекте.

## Что входит в раздел

- [Создание геозон](Геозоны/Создание геозон.md) — типы геозон, нанесение на карту
- [Свойства геозон](Геозоны/Свойства геозон.md) — справочник параметров
- [Работа с геозонами](Геозоны/Работа с геозонами.md) — списки, фильтры, отображение
- [Группы геозон](Геозоны/Группы геозон.md) — объединение для удобства
- [Применение геозон](Геозоны/Применение геозон.md) — где используются

Чего НЕ должно быть в обзорной странице

Когда обзорная страница не нужна

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

13. Топ-10 ошибок

Топ-10 ошибок, которые делают авторы. Если видишь это у себя — поправь.

14. Чек-лист перед публикацией

Прежде чем сохранять статью — пройдись по этому списку.

15. Куда смотреть у Wialon

Когда не уверен, как оформить — открывай аналогичную страницу у Wialon и смотри.

Хорошие образцы для каждого типа

Overview-страница сущности

Создание

Работа с

Применение

Группы

Свойства с таблицей

Хаб с навигацией

Лайфхак

Когда начинаешь писать статью про новую сущность — сначала найди её аналог в Wialon, изучи раскладку файлов, скопируй структуру 1:1, потом заполни своим содержимым. Это сэкономит часы споров «как правильно».

16. Частые вопросы