Руководство по написанию технической документации SKIF.PRO

Для кого этот документ: авторы статей (техподдержка, продакт-менеджеры, разработчики, аналитики) и AI-агент первичной проверки.

Почему это важно: статья работает правильно только если автор точно знает, кто её будет читать и зачем. От этого зависят структура, язык и глубина проработки.

Связанные документы:

• wiki-structure-guidelines.md — правила размещения статьи в структуре Wiki
• ai-checklist.md — единый чек-лист для AI-агента проверки

Часть 1. Принцип «От кого → Кому»: фундамент качества статьи

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

1. Кто источник информации? (кто владеет знанием)
2. Кто получатель? (кто будет читать и зачем)

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

1.1. Матрица стейкхолдеров

Получатели (читатели)

Источники (авторы и владельцы информации)

1.2. Определение пары «Источник → Получатель»

Алгоритм выбора для автора:

1. Кто инициировал создание статьи?
   → Это подсказка по источнику (S1–S4)

2. Кто будет читать эту статью?
   → Конечный клиент (R1) или интегратор (R2)?

3. Какую задачу решает читатель?
   → Одна задача = одна статья

Типовые пары и их смысл:

⚠️ Запрещённые ситуации:

• Статья адресована «всем» — это означает, что она не адресована никому
• Один документ одновременно объясняет концепцию клиенту и содержит технический справочник для интегратора
• Автор пишет то, что знает сам, не думая о получателе

Часть 2. Типы статей и их структуры

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

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

Вне scope этого документа:

• API-документация ведётся в Postman (отдельный workflow)
• Release Notes публикуются на сайте (отдельный workflow)

Тип A: Инструкция для конечного клиента

Пары: S1→R1, S2→R1

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

Признаки правильной статьи типа A:

• Написана от второго лица («нажмите», «выберите», «перейдите»)
• Не содержит технических терминов без объяснения
• Каждый шаг — одно действие
• Есть скриншоты для неочевидных шагов
• Скриншоты сопровождаются текстовым описанием (AI-агент не видит изображения)

Обязательная структура:

Пример:

# Как добавить транспортное средство

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

## Что потребуется
- Роль «Редактор» или выше
- IMEI-номер трекера (указан на корпусе устройства или в документации к нему)

## Пошаговая инструкция

1. Перейдите в раздел **Объекты**.
2. Нажмите кнопку **Создать объект** в правом верхнем углу.
3. В поле **Название** введите имя транспортного средства.
   Используйте описательное название, например, «МАЗ-5440 А123ВС» вместо «М1».
4. В поле **IMEI** введите номер трекера.
5. Нажмите **Сохранить**.

## Частые вопросы и ошибки

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

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

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

Тип B: Концепция (описание функциональности)

Пары: S2→R1, S2→R2, S4→R2

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

Признаки правильной статьи типа B:

• Отвечает на вопрос «зачем это нужно» и «как это устроено», а не «как нажать»
• Описывает бизнес-логику и сценарии применения
• Может содержать схемы и диаграммы
• Не дублирует пошаговые инструкции — даёт ссылки на них
• Для R1 — аналогии и примеры из жизни, для R2 — логика системы и модели данных

Обязательная структура:

Тип C: Справочник интерфейса

Пары: S2→R1, S3→R1

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

Признаки правильной статьи типа C:

• Привязана к одному конкретному экрану или вкладке (одна вкладка = одна статья)
• Перечисляет поля, их назначение, допустимые значения, значения по умолчанию
• Не учит «как», описывает «что» — пошаговые действия выносятся в тип A
• Содержит скриншот экрана с текстовым описанием

Обязательная структура:

Пример:

# Карточка объекта — вкладка «Основные»

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

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

## Описание полей

| Поле | Описание | Допустимые значения | По умолчанию |
|------|----------|---------------------|--------------|
| **Название** | Отображаемое имя объекта на карте и в отчётах | Текст, до 100 символов | — |
| **IMEI** | Идентификатор трекера | 15 цифр | — |
| **Тип объекта** | Категория транспорта | Легковой, Грузовой, Спецтехника, Человек | Легковой |
| **Иконка** | Значок объекта на карте | Выбор из библиотеки | Автомобиль |

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

Тип D: Устранение неполадок (Troubleshooting)

Пары: S1→R1, S1→R2, S3→R2

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

Признаки правильной статьи типа D:

• Заголовок — описание симптома словами получателя, а не технической причиной
• Решения идут от простого к сложному
• Есть явный раздел «когда обращаться в поддержку»
• Для R2: допустимы технические детали (коды ошибок, логи, curl-примеры)

Обязательная структура:

Пример для R1:

# Трекер не выходит на связь

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

## Возможные причины и решения

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

### Причина 2: Нет покрытия GSM-сети
Трекер находится в зоне без мобильной связи (подземная парковка, удалённая территория).
**Решение:** Переместите транспорт в зону покрытия. Данные передадутся автоматически.

## Если ничего не помогло
Обратитесь в техподдержку и сообщите:
- IMEI трекера
- Время последней связи из карточки объекта
- Какие шаги уже выполнены

Пример для R2:

# Webhook не доставляет события

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

## Возможные причины и решения

### Причина 1: Эндпоинт недоступен извне
SKIF.PRO не может установить TCP-соединение с указанным URL.
**Решение:** Убедитесь, что URL доступен из интернета. Проверьте командой:
`curl -X POST https://your-endpoint.com/webhook -d '{"test": true}'`

### Причина 2: Эндпоинт отвечает не 200
SKIF.PRO считает доставку успешной только при HTTP 200.
**Решение:** Убедитесь, что ваш сервер возвращает именно статус 200 (не 201, не 204).

## Если ничего не помогло
Обратитесь в техподдержку и сообщите:
- URL webhook-эндпоинта
- Тип события, на которое подписаны
- Логи вашего сервера за последний час

Часть 3. Требования к тексту

3.1. Заголовки

3.2. Язык для R1 (конечный клиент)

• Одна мысль — одно предложение. Ориентир: не более 25 слов на предложение.
• Нет жаргона: вместо «задеплоить» → «применить изменения»
• Нет пассивного залога: вместо «значение должно быть введено» → «введите значение»
• Названия кнопок и разделов — жирным, точь-в-точь как в интерфейсе
• Каждый шаг — одно действие

3.3. Язык для R2 (интегратор)

• Технические термины допустимы и ожидаемы
• Все типы данных указываются явно: string, integer, boolean, ISO 8601
• Граничные случаи и исключения — обязательны
• Конкретные значения вместо абстрактных описаний

3.4. Атомарность

Одна статья = один вопрос читателя.

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

• В ней несколько заголовков уровня H2, которые могут быть самостоятельными статьями
• Она одновременно объясняет концепцию И содержит пошаговую инструкцию (разбить на тип B + тип A)
• Она одновременно описывает «как сделать» И перечисляет все поля формы (разбить на тип A + тип C)
• Она адресована и R1, и R2 одновременно

3.5. Глубина заголовков

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

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

3.6. Самодостаточность секций (для AI-агента)

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

• Каждая секция (блок под H2) должна быть понятна без чтения остальных секций
• Запрещены ссылки «как описано выше», «см. предыдущий раздел»
• Называйте сущности явно: вместо «эта функция» → «функция геозон»
• Короткие повторяющиеся факты (роль доступа, версия) дублируйте в каждой статье
• Развёрнутые блоки (описание алгоритма, большая таблица) не дублируйте — давайте ссылку с кратким резюме в 1 предложение

3.7. Скриншоты

• Каждый скриншот обязательно сопровождается текстовым описанием действия. AI-агент не видит изображения.
• Скриншот размещается непосредственно после шага, который он иллюстрирует
• Критичную информацию из таблиц на скриншотах дублируйте в текстовой таблице

3.8. Перекрёстные ссылки

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

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

> 🔧 Техническая статья для интеграторов: [Протокол обмена данными с трекерами](ссылка)

> 📱 Статья для пользователей: [Как добавить транспортное средство](ссылка)

Формат ссылок:

• ✅ см. статью «Как создать объект»
• ❌ см. здесь
• ❌ подробнее по ссылке

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

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

Блок 1: Стейкхолдеры (критично)

• Указана пара «Источник → Получатель» в метаданных
• Получатель однозначно определён: R1 (клиент) или R2 (интегратор), не оба
• Содержание соответствует нуждам указанного получателя
• Тип статьи (A/B/C/D) соответствует паре и задаче читателя

Блок 2: Место в структуре Wiki (критично)

• Определён раздел верхнего уровня (Объекты / Геозоны / Отчёты / ...)
• Определён подраздел, статья размещена в правильном месте иерархии (см. wiki-structure-guidelines.md)
• Название статьи соответствует правилам именования для её типа
• Статья не дублирует уже существующую — при пересечении тем используется ссылка

Блок 3: Структура и содержание (критично)

• Используется обязательная структура для данного типа статьи
• Все обязательные секции присутствуют
• Статья атомарна: одна задача — один документ
• Заголовки не глубже H3
• Для типа A: каждый шаг проверяем в реальном интерфейсе
• Для типа C: все поля имеют описание и допустимые значения
• Для типа D: решения идут от простого к сложному

Блок 4: Язык и оформление (важно)

• Язык соответствует аудитории (простой для R1, технический для R2)
• Названия элементов интерфейса выделены жирным и совпадают с реальным UI
• Нет пассивного залога в инструкциях для R1
• Нет неопределённых местоимений («это», «данный», «соответствующий»)
• Скриншоты сопровождаются текстовым описанием
• Перекрёстные ссылки R1↔R2 маркированы

Блок 5: Тестирование (критично для типов A, D)

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

Как проводится тестирование:

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

Результат тестирования:

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

Чек-лист тестировщика:

• Все шаги выполнены в реальном интерфейсе системы
• Названия всех кнопок, полей и разделов совпадают с реальным UI
• Итоговый результат соответствует заявленному в статье
• Раздел «Частые ошибки» проверен: описанные ошибки реально воспроизводятся и решаются указанным способом

Обязательность тестирования по типам:

• Тип A (Инструкция) — обязательно
• Тип D (Troubleshooting) — обязательно
• Тип B (Концепция) — не требуется (нет шагов)
• Тип C (Справочник интерфейса) — рекомендуется (проверить, что описания полей соответствуют реальному UI)

Блок 6: AI-специфические требования (для агента поддержки)

• Каждый раздел самодостаточен при извлечении фрагментами
• Симптомы и ошибки описаны словами пользователя, а не техническими кодами
• Нет ссылок вида «как описано выше» или «см. предыдущий раздел»
• Ключевые термины и синонимы присутствуют в тексте (не только в заголовке)

Часть 5. Метаданные статьи

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

---
type: A | B | C | D               # Тип статьи
source: S1 | S2 | S3 | S4         # Роль источника информации
audience: R1 | R2                  # Получатель (только один)
section: [раздел/подраздел]        # Место в структуре Wiki (из wiki-structure-guidelines.md)
owner: [имя или команда]           # Кто отвечает за актуальность
last_verified: ГГГГ-ММ-ДД         # Дата последней проверки на актуальность
tested_by: [имя тестировщика]      # Кто провёл практическое тестирование (обязательно для A, D)
version: [версия продукта]         # Версия, к которой относится
---

Правила заполнения:

• Поле audience принимает только одно значение. Если информация нужна обеим аудиториям — создаются два документа.
• Поле section должно точно соответствовать разделу/подразделу из wiki-structure-guidelines.md.
• Поле tested_by обязательно для типов A и D. Пустое поле блокирует публикацию.

Часть 6. Жизненный цикл статьи

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

[1] ПОСТАНОВКА ЗАДАЧИ
    Определить: пару Source→Receiver, тип статьи, место в структуре Wiki.
    Заполнить: шаблон задачи на документирование (см. раздел 6.1).
         ↓
[2] НАПИСАНИЕ
    Автор создаёт черновик по обязательной структуре для своего типа.
         ↓
[3] РЕВЬЮ
    ├── Фактчекинг: стейкхолдер-источник проверяет точность данных
    ├── Структура и стиль: технический писатель проверяет соответствие гайду
    └── AI-агент: первичная автоматическая проверка по чек-листу (ai-checklist.md)
         ↓
[4] ТЕСТИРОВАНИЕ (обязательно для типов A, D; рекомендуется для C)
    Тестировщик проходит все шаги в реальной системе строго по тексту статьи.
    Результат: ✅ Пройдено → переход к публикации
               ❌ Возвращено → автор дорабатывает → повторное тестирование
         ↓
[5] ПУБЛИКАЦИЯ
    Статья размещается в правильном разделе/подразделе Wiki.
         ↓
[6] АКТУАЛИЗАЦИЯ (ongoing)
    Владелец обновляет статью при каждом изменении функциональности.

6.1. Шаблон задачи на документирование

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

Часть 7. Правила актуализации

Статья устаревает в момент, когда:

• Изменился интерфейс или поведение функции
• Изменились бизнес-правила или логика работы
• Пользователи задают вопросы, ответы на которые должны быть в статье

Ответственность за актуализацию:

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