---

Каждая статья в вики — это **канал коммуникации между двумя конкретными сторонами**. Перед началом работы автор обязан ответить на два вопроса:

1. **Кто источник информации?** (кто владеет знанием)

2. **Кто получатель?** (кто будет читать и зачем)

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

---

| ID | Роль | Кто это | Контекст чтения |

|----|------|---------|-----------------|

| `R1` | **Конечный клиент** | Пользователь продукта SKIF.PRO: диспетчер, логист, руководитель автопарка | Решает конкретную задачу прямо сейчас. Не знает технических деталей. Ожидает пошаговые инструкции. |

| `R2` | **Интегратор** | Технический специалист компании-партнёра, который внедряет или настраивает SKIF.PRO у клиента | Ищет точные технические параметры: форматы, схемы, ограничения. Умеет читать технические тексты. |

| ID | Роль | Кто это | Что может рассказать |

|----|------|---------|----------------------|

| `S1` | **Техподдержка** | Специалисты первой и второй линии поддержки | Типовые проблемы пользователей, сценарии ошибок, FAQ по реальным обращениям |

| `S2` | **Продакт-менеджер** | Владелец продукта или менеджер по продукту | Описание новых фич, бизнес-логика, критерии использования функций |

| `S3` | **Разработчик** | Backend/Frontend/DevOps инженер | Технические детали реализации, форматы данных, ограничения системы |

| `S4` | **Системный/бизнес-аналитик** | Аналитик, участвовавший в проектировании | Логика работы функциональности, граничные случаи, бизнес-правила |

| `S5` | **Технический писатель** | Специалист по документации | Структура, стиль, архитектура информации — не источник фактов, но имплементатор канала |

---

| Пара | Когда используется | Пример статьи |

|------|--------------------|---------------|

| `S1 → R1` | Техподдержка передаёт решение частой проблемы клиенту | «Почему трекер не отображается на карте» |

| `S2 → R1` | Продакт рассказывает клиенту о новой функции | «Как использовать автоматические отчёты» |

| `S2 → R2` | Продакт объясняет интегратору логику новой фичи | «Модель данных объектов: структура и ограничения» |

| `S3 → R2` | Разработчик документирует технические детали интеграции | «Протокол обмена данными с трекерами» |

| `S4 → R2` | Аналитик описывает бизнес-правила для интеграции | «Правила расчёта пробега: алгоритм и исключения» |

| `S1 → R2` | Поддержка описывает типовые ошибки при внедрении | «Частые ошибки при настройке CAN-шины» |

---

Тип статьи определяется **парой «Источник → Получатель»** и **задачей читателя**.

В Wiki SKIF.PRO используются **четыре типа статей**:

| Тип | Название | Отвечает на вопрос | Аудитория |

|-----|----------|-------------------|-----------|

| **A** | Инструкция | «Как сделать X?» | R1 |

| **B** | Концепция | «Что это и зачем?» | R1 или R2 |

| **C** | Справочник интерфейса | «Что означают эти поля/настройки?» | R1 |

| **D** | Troubleshooting | «Почему не работает и что делать?» | R1 или R2 |

---

**Когда создаётся:** клиент должен самостоятельно выполнить задачу в интерфейсе системы.

- Написана от второго лица («нажмите», «выберите», «перейдите»)

- Не содержит технических терминов без объяснения

- Каждый шаг — одно действие

- Есть скриншоты для неочевидных шагов

- Скриншоты сопровождаются текстовым описанием (AI-агент не видит изображения)

| Секция | Обязательность | Назначение |

|--------|:---:|---|

| `# [Глагол + задача]` | ✅ обязательно | Заголовок = поисковый запрос |

| `## Когда это нужно` | ✅ обязательно | Жизненный сценарий, 1–3 предложения |

| `## Что потребуется` | ⚙️ условно | Только если есть предусловия (права, данные). Если нет — пропускается |

| `## Пошаговая инструкция` | ✅ обязательно | Нумерованные шаги, одно действие на шаг |

| `## Частые вопросы и ошибки` | ✅ обязательно | Симптом → причина → решение |

| `## Что дальше` | 💡 рекомендуемо | 2–3 ссылки на следующие действия |

Вы приобрели новый трекер и хотите начать отслеживать транспортное средство в системе SKIF.PRO.

- Роль «Редактор» или выше

- IMEI-номер трекера (указан на корпусе устройства или в документации к нему)

1. Перейдите в раздел **Объекты**.

2. Нажмите кнопку **Создать объект** в правом верхнем углу.

3. В поле **Название** введите имя транспортного средства.

Используйте описательное название, например, «МАЗ-5440 А123ВС» вместо «М1».

4. В поле **IMEI** введите номер трекера.

5. Нажмите **Сохранить**.

Кнопка доступна только пользователям с ролью «Редактор» и выше. Обратитесь к администратору аккаунта.

Объект появится на карте после того, как трекер передаст первые координаты. Убедитесь, что трекер включен и настроен на сервер SKIF.PRO.

- Настройте датчики объекта — см. статью «Карточка объекта — вкладка Датчики»

- Добавьте объект в группу — см. статью «Как добавить объект в группу»

---

**Когда создаётся:** нужно объяснить, *что* делает функция и *зачем*, прежде чем показывать *как*.

- Отвечает на вопрос «зачем это нужно» и «как это устроено», а не «как нажать»

- Описывает бизнес-логику и сценарии применения

- Может содержать схемы и диаграммы

- Не дублирует пошаговые инструкции — даёт ссылки на них

- Для R1 — аналогии и примеры из жизни, для R2 — логика системы и модели данных

| Секция | Обязательность | Назначение |

|--------|:---:|---|

| `# [Название функциональности]` | ✅ обязательно | Для R1: «Что такое X в SKIF.PRO». Для R2: «X: модель данных и логика» |

| `## Для чего это нужно` | ✅ обязательно | Бизнес-задача языком получателя |

| `## Как это работает` | ✅ обязательно | Принцип работы. Для R1 — простым языком. Для R2 — техническая логика |

| `## Сценарии применения` | ✅ обязательно | 2–4 сценария использования |

| `## Ограничения и важные условия` | ✅ обязательно | Граничные случаи, зависимости от тарифа/настроек |

| `## Связанные инструкции` | 💡 рекомендуемо | Ссылки на статьи типа A |

---

**Когда создаётся:** нужно описать конкретный экран, вкладку или форму — перечислить все поля с их назначением и допустимыми значениями.

- Привязана к одному конкретному экрану или вкладке (одна вкладка = одна статья)

- Перечисляет поля, их назначение, допустимые значения, значения по умолчанию

- Не учит «как», описывает «что» — пошаговые действия выносятся в тип A

- Содержит скриншот экрана с текстовым описанием

| Секция | Обязательность | Назначение |

|--------|:---:|---|

| `# [Название экрана — вкладка/форма]` | ✅ обязательно | Точное название как в интерфейсе |

| `## Назначение` | ✅ обязательно | 1–2 предложения: для чего используется экран |

| `## Как открыть` | ✅ обязательно | Краткий путь навигации (без полной инструкции) |

| `## Описание полей` | ✅ обязательно | Таблица: поле, описание, допустимые значения, по умолчанию |

| `## Связанные инструкции` | 💡 рекомендуемо | Ссылки на статьи типа A, которые используют этот экран |

Вкладка содержит базовые параметры объекта мониторинга: название, тип, привязку к трекеру.

**Объекты** → выберите объект → вкладка **Основные**.

| Поле | Описание | Допустимые значения | По умолчанию |

|------|----------|---------------------|--------------|

| **Название** | Отображаемое имя объекта на карте и в отчётах | Текст, до 100 символов | — |

| **IMEI** | Идентификатор трекера | 15 цифр | — |

| **Тип объекта** | Категория транспорта | Легковой, Грузовой, Спецтехника, Человек | Легковой |

| **Иконка** | Значок объекта на карте | Выбор из библиотеки | Автомобиль |

- Как создать объект — см. статью «Как добавить транспортное средство»

- Как изменить тип объекта — см. статью «Как редактировать объект»

---

**Когда создаётся:** техподдержка или разработчики фиксируют повторяющиеся проблемы с решениями.

- Заголовок — описание симптома словами получателя, а не технической причиной

- Решения идут от простого к сложному

- Есть явный раздел «когда обращаться в поддержку»

- Для R2: допустимы технические детали (коды ошибок, логи, curl-примеры)

| Секция | Обязательность | Назначение |

|--------|:---:|---|

| `# [Симптом словами получателя]` | ✅ обязательно | Для R1: «Трекер не выходит на связь». Для R2: «Запрос возвращает ошибку 502» |

| `## Симптом` | ✅ обязательно | Точное описание: что видит получатель |

| `## Возможные причины и решения` | ✅ обязательно | H3 для каждой причины: диагностика + решение |

| `## Если ничего не помогло` | ✅ обязательно | Что сообщить в поддержку, какие данные подготовить |

Объект на карте отображается серым. В карточке объекта в поле **Последняя связь** указано время более 30 минут назад.

Проверьте, горит ли индикатор питания на трекере.

**Решение:** Подключите трекер к питанию и дождитесь загрузки (1–3 минуты).

Трекер находится в зоне без мобильной связи (подземная парковка, удалённая территория).

**Решение:** Переместите транспорт в зону покрытия. Данные передадутся автоматически.

Обратитесь в техподдержку и сообщите:

- IMEI трекера

- Время последней связи из карточки объекта

- Какие шаги уже выполнены

Настроенный webhook-эндпоинт не получает POST-запросы от SKIF.PRO при наступлении события.

SKIF.PRO не может установить TCP-соединение с указанным URL.

**Решение:** Убедитесь, что URL доступен из интернета. Проверьте командой:

SKIF.PRO считает доставку успешной только при HTTP 200.

**Решение:** Убедитесь, что ваш сервер возвращает именно статус 200 (не 201, не 204).

Обратитесь в техподдержку и сообщите:

- URL webhook-эндпоинта

- Тип события, на которое подписаны

- Логи вашего сервера за последний час

---

| Правило | Правильно | Неправильно |

|---------|-----------|-------------|

| Для инструкций (A) — начинать с глагола | «Как создать геозону» | «Геозоны. Создание» |

| Для концепций (B) — R1: «Что такое…»; R2: объект + контекст | «Что такое геозоны в SKIF.PRO» / «Геозоны: модель данных и ограничения» | «Введение в геозоны» |

| Для справочников (C) — название экрана | «Карточка объекта — вкладка Основные» | «Основные настройки объекта» |

| Для troubleshooting (D) — симптом словами получателя | «Почему трекер офлайн» | «Статус трекера» |

| Не использовать аббревиатуры без расшифровки | «Настройка CAN-шины (бортовой сети)» | «Настройка CAN» |

- Одна мысль — одно предложение. Ориентир: не более 25 слов на предложение.

- Нет жаргона: вместо «задеплоить» → «применить изменения»

- Нет пассивного залога: вместо «значение должно быть введено» → «введите значение»

- Названия кнопок и разделов — **жирным**, точь-в-точь как в интерфейсе

- Каждый шаг — одно действие

- Технические термины допустимы и ожидаемы

- Все типы данных указываются явно: `string`, `integer`, `boolean`, `ISO 8601`

- Граничные случаи и исключения — обязательны

- Конкретные значения вместо абстрактных описаний

Статья нарушает принцип атомарности, если:

- В ней несколько заголовков уровня H2, которые могут быть самостоятельными статьями

- Она одновременно объясняет концепцию И содержит пошаговую инструкцию (разбить на тип B + тип A)

- Она одновременно описывает «как сделать» И перечисляет все поля формы (разбить на тип A + тип C)

- Она адресована и R1, и R2 одновременно

Максимальная глубина заголовков внутри статьи — **H3** (`###`). Если требуется более глубокая вложенность — это сигнал, что статья нарушает атомарность и должна быть разделена.

Исключение: тип D (Troubleshooting) использует H3 для отдельных причин внутри секции «Возможные причины и решения». Вложенность внутри причины не допускается.

AI-агент техподдержки извлекает фрагменты статей, а не читает их целиком. Поэтому:

- Каждая секция (блок под H2) должна быть понятна без чтения остальных секций

- Запрещены ссылки «как описано выше», «см. предыдущий раздел»

- Называйте сущности явно: вместо «эта функция» → «функция геозон»

- Короткие повторяющиеся факты (роль доступа, версия) дублируйте в каждой статье

- Развёрнутые блоки (описание алгоритма, большая таблица) не дублируйте — давайте ссылку с кратким резюме в 1 предложение

- Каждый скриншот обязательно сопровождается текстовым описанием действия. AI-агент не видит изображения.

- Скриншот размещается непосредственно после шага, который он иллюстрирует

- Критичную информацию из таблиц на скриншотах дублируйте в текстовой таблице

**Внутри одной аудитории (R1→R1 или R2→R2):** свободно, по полному названию статьи.

**Между аудиториями (R1↔R2):** допустимы, но обязательно маркируются:

- ✅ `см. статью «Как создать объект»`

- ❌ `см. здесь`

- ❌ `подробнее по ссылке`

---

Используется автором при самопроверке. Полный машиночитаемый чек-лист для AI-агента — в файле `ai-checklist.md`.

- [ ] Указана пара «Источник → Получатель» в метаданных

- [ ] Получатель однозначно определён: `R1` (клиент) или `R2` (интегратор), не оба

- [ ] Содержание соответствует нуждам указанного получателя

- [ ] Тип статьи (A/B/C/D) соответствует паре и задаче читателя

- [ ] Определён раздел верхнего уровня (Объекты / Геозоны / Отчёты / ...)

- [ ] Определён подраздел, статья размещена в правильном месте иерархии (см. `wiki-structure-guidelines.md`)

- [ ] Название статьи соответствует правилам именования для её типа

- [ ] Статья не дублирует уже существующую — при пересечении тем используется ссылка

- [ ] Используется обязательная структура для данного типа статьи

- [ ] Все обязательные секции присутствуют

- [ ] Статья атомарна: одна задача — один документ

- [ ] Заголовки не глубже H3

- [ ] Для типа A: каждый шаг проверяем в реальном интерфейсе

- [ ] Для типа C: все поля имеют описание и допустимые значения

- [ ] Для типа D: решения идут от простого к сложному

- [ ] Язык соответствует аудитории (простой для R1, технический для R2)

- [ ] Названия элементов интерфейса выделены жирным и совпадают с реальным UI

- [ ] Нет пассивного залога в инструкциях для R1

- [ ] Нет неопределённых местоимений («это», «данный», «соответствующий»)

- [ ] Скриншоты сопровождаются текстовым описанием

- [ ] Перекрёстные ссылки R1↔R2 маркированы

**Каждая статья, содержащая шаги, должна пройти практическое тестирование до публикации.** Тестирование проводит тестировщик или ответственный стейкхолдер — не автор.

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

2. Каждый шаг должен воспроизводиться точно так, как написано: кнопка с указанным названием существует, поле называется именно так, переход происходит туда, куда указано.

3. По итогу тестировщик должен получить тот результат, который заявлен в статье.

- `✅ Пройдено` — все шаги воспроизводятся, результат достигнут. Статья может быть опубликована.

- `❌ Возвращено на доработку` — тестировщик фиксирует, на каком шаге возникло расхождение, и возвращает статью автору с конкретными замечаниями.

- [ ] Все шаги выполнены в реальном интерфейсе системы

- [ ] Названия всех кнопок, полей и разделов совпадают с реальным UI

- [ ] Итоговый результат соответствует заявленному в статье

- [ ] Раздел «Частые ошибки» проверен: описанные ошибки реально воспроизводятся и решаются указанным способом

- [ ] Каждый раздел самодостаточен при извлечении фрагментами

- [ ] Симптомы и ошибки описаны словами пользователя, а не техническими кодами

- [ ] Нет ссылок вида «как описано выше» или «см. предыдущий раздел»

- [ ] Ключевые термины и синонимы присутствуют в тексте (не только в заголовке)

---

Каждая статья должна начинаться с блока метаданных (YAML front matter):

- Поле `audience` принимает **только одно значение**. Если информация нужна обеим аудиториям — создаются два документа.

- Поле `section` должно точно соответствовать разделу/подразделу из `wiki-structure-guidelines.md`.

- Поле `tested_by` обязательно для типов A и D. Пустое поле блокирует публикацию.

---

Каждая статья проходит следующие обязательные этапы перед публикацией:

При постановке задачи на создание или обновление статьи инициатор заполняет:

| Поле | Описание | Пример |

|------|----------|--------|

| **Триггер** | Что вызвало необходимость | «Добавлена фича X в релизе 2.5» |

| **Стейкхолдеры** | Источник → Получатель | `S2 → R1` |

| **Тип статьи** | A / B / C / D | A (Инструкция) |

| **Объём** | Какая функциональность покрывается | «Создание геозоны через UI» |

| **Эксперт для интервью** | Кто владеет знанием | «Иванов И.И., backend-разработчик» |

| **Дедлайн** | Когда нужна готовая статья | «До конца спринта 14» |

---

- Изменился интерфейс или поведение функции

- Изменились бизнес-правила или логика работы

- Пользователи задают вопросы, ответы на которые должны быть в статье

| Триггер | Кто обновляет | Срок |

|---------|--------------|------|

| Новый релиз с изменением фичи | Автор статьи (владелец) | В рамках спринта релиза |

| Сигнал от техподдержки (статья вводит в заблуждение) | Техписатель + владелец | Не позднее 2 рабочих дней |

| Плановая проверка | Технический писатель | Ежеквартально |

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