Commit aafe1b
2026-02-18 14:31:55 Dima: 123| /dev/null .. руководство по написанию технической документации.md | |
| @@ 0,0 1,540 @@ | |
| + | # Руководство по написанию технической документации SKIF.PRO |
| + | |
| + | > **Для кого этот документ:** авторы статей (техподдержка, продакт-менеджеры, разработчики, аналитики) и AI-агент первичной проверки. |
| + | > |
| + | > **Почему это важно:** статья работает правильно только если автор точно знает, кто её будет читать и зачем. От этого зависят структура, язык и глубина проработки. |
| + | > |
| + | > **Связанные документы:** |
| + | > - `wiki-structure-guidelines.md` — правила размещения статьи в структуре Wiki |
| + | > - `ai-checklist.md` — единый чек-лист для AI-агента проверки |
| + | |
| + | --- |
| + | |
| + | ## Часть 1. Принцип «От кого → Кому»: фундамент качества статьи |
| + | |
| + | Каждая статья в вики — это **канал коммуникации между двумя конкретными сторонами**. Перед началом работы автор обязан ответить на два вопроса: |
| + | |
| + | 1. **Кто источник информации?** (кто владеет знанием) |
| + | 2. **Кто получатель?** (кто будет читать и зачем) |
| + | |
| + | Качество статьи измеряется тем, насколько точно она закрывает потребность получателя — не больше и не меньше. |
| + | |
| + | --- |
| + | |
| + | ### 1.1. Матрица стейкхолдеров |
| + | |
| + | #### Получатели (читатели) |
| + | |
| + | | ID | Роль | Кто это | Контекст чтения | |
| + | |----|------|---------|-----------------| |
| + | | `R1` | **Конечный клиент** | Пользователь продукта SKIF.PRO: диспетчер, логист, руководитель автопарка | Решает конкретную задачу прямо сейчас. Не знает технических деталей. Ожидает пошаговые инструкции. | |
| + | | `R2` | **Интегратор** | Технический специалист компании-партнёра, который внедряет или настраивает SKIF.PRO у клиента | Ищет точные технические параметры: форматы, схемы, ограничения. Умеет читать технические тексты. | |
| + | |
| + | #### Источники (авторы и владельцы информации) |
| + | |
| + | | ID | Роль | Кто это | Что может рассказать | |
| + | |----|------|---------|----------------------| |
| + | | `S1` | **Техподдержка** | Специалисты первой и второй линии поддержки | Типовые проблемы пользователей, сценарии ошибок, FAQ по реальным обращениям | |
| + | | `S2` | **Продакт-менеджер** | Владелец продукта или менеджер по продукту | Описание новых фич, бизнес-логика, критерии использования функций | |
| + | | `S3` | **Разработчик** | Backend/Frontend/DevOps инженер | Технические детали реализации, форматы данных, ограничения системы | |
| + | | `S4` | **Системный/бизнес-аналитик** | Аналитик, участвовавший в проектировании | Логика работы функциональности, граничные случаи, бизнес-правила | |
| + | | `S5` | **Технический писатель** | Специалист по документации | Структура, стиль, архитектура информации — не источник фактов, но имплементатор канала | |
| + | |
| + | --- |
| + | |
| + | ### 1.2. Определение пары «Источник → Получатель» |
| + | |
| + | **Алгоритм выбора для автора:** |
| + | |
| + | ``` |
| + | 1. Кто инициировал создание статьи? |
| + | → Это подсказка по источнику (S1–S4) |
| + | |
| + | 2. Кто будет читать эту статью? |
| + | → Конечный клиент (R1) или интегратор (R2)? |
| + | |
| + | 3. Какую задачу решает читатель? |
| + | → Одна задача = одна статья |
| + | ``` |
| + | |
| + | **Типовые пары и их смысл:** |
| + | |
| + | | Пара | Когда используется | Пример статьи | |
| + | |------|--------------------|---------------| |
| + | | `S1 → R1` | Техподдержка передаёт решение частой проблемы клиенту | «Почему трекер не отображается на карте» | |
| + | | `S2 → R1` | Продакт рассказывает клиенту о новой функции | «Как использовать автоматические отчёты» | |
| + | | `S2 → R2` | Продакт объясняет интегратору логику новой фичи | «Модель данных объектов: структура и ограничения» | |
| + | | `S3 → R2` | Разработчик документирует технические детали интеграции | «Протокол обмена данными с трекерами» | |
| + | | `S4 → R2` | Аналитик описывает бизнес-правила для интеграции | «Правила расчёта пробега: алгоритм и исключения» | |
| + | | `S1 → R2` | Поддержка описывает типовые ошибки при внедрении | «Частые ошибки при настройке CAN-шины» | |
| + | |
| + | > ⚠️ **Запрещённые ситуации:** |
| + | > - Статья адресована «всем» — это означает, что она не адресована никому |
| + | > - Один документ одновременно объясняет концепцию клиенту и содержит технический справочник для интегратора |
| + | > - Автор пишет то, что знает сам, не думая о получателе |
| + | |
| + | --- |
| + | |
| + | ## Часть 2. Типы статей и их структуры |
| + | |
| + | Тип статьи определяется **парой «Источник → Получатель»** и **задачей читателя**. |
| + | |
| + | В Wiki SKIF.PRO используются **четыре типа статей**: |
| + | |
| + | | Тип | Название | Отвечает на вопрос | Аудитория | |
| + | |-----|----------|-------------------|-----------| |
| + | | **A** | Инструкция | «Как сделать X?» | R1 | |
| + | | **B** | Концепция | «Что это и зачем?» | R1 или R2 | |
| + | | **C** | Справочник интерфейса | «Что означают эти поля/настройки?» | R1 | |
| + | | **D** | Troubleshooting | «Почему не работает и что делать?» | R1 или R2 | |
| + | |
| + | > **Вне scope этого документа:** |
| + | > - API-документация ведётся в Postman (отдельный workflow) |
| + | > - Release Notes публикуются на сайте (отдельный workflow) |
| + | |
| + | --- |
| + | |
| + | ### Тип A: Инструкция для конечного клиента |
| + | *Пары: `S1→R1`, `S2→R1`* |
| + | |
| + | **Когда создаётся:** клиент должен самостоятельно выполнить задачу в интерфейсе системы. |
| + | |
| + | **Признаки правильной статьи типа A:** |
| + | - Написана от второго лица («нажмите», «выберите», «перейдите») |
| + | - Не содержит технических терминов без объяснения |
| + | - Каждый шаг — одно действие |
| + | - Есть скриншоты для неочевидных шагов |
| + | - Скриншоты сопровождаются текстовым описанием (AI-агент не видит изображения) |
| + | |
| + | **Обязательная структура:** |
| + | |
| + | | Секция | Обязательность | Назначение | |
| + | |--------|:---:|---| |
| + | | `# [Глагол + задача]` | ✅ обязательно | Заголовок = поисковый запрос | |
| + | | `## Когда это нужно` | ✅ обязательно | Жизненный сценарий, 1–3 предложения | |
| + | | `## Что потребуется` | ⚙️ условно | Только если есть предусловия (права, данные). Если нет — пропускается | |
| + | | `## Пошаговая инструкция` | ✅ обязательно | Нумерованные шаги, одно действие на шаг | |
| + | | `## Частые вопросы и ошибки` | ✅ обязательно | Симптом → причина → решение | |
| + | | `## Что дальше` | 💡 рекомендуемо | 2–3 ссылки на следующие действия | |
| + | |
| + | **Пример:** |
| + | |
| + | ```markdown |
| + | # Как добавить транспортное средство |
| + | |
| + | ## Когда это нужно |
| + | Вы приобрели новый трекер и хотите начать отслеживать транспортное средство в системе SKIF.PRO. |
| + | |
| + | ## Что потребуется |
| + | - Роль «Редактор» или выше |
| + | - IMEI-номер трекера (указан на корпусе устройства или в документации к нему) |
| + | |
| + | ## Пошаговая инструкция |
| + | |
| + | 1. Перейдите в раздел **Объекты**. |
| + | 2. Нажмите кнопку **Создать объект** в правом верхнем углу. |
| + | 3. В поле **Название** введите имя транспортного средства. |
| + | Используйте описательное название, например, «МАЗ-5440 А123ВС» вместо «М1». |
| + | 4. В поле **IMEI** введите номер трекера. |
| + | 5. Нажмите **Сохранить**. |
| + | |
| + | ## Частые вопросы и ошибки |
| + | |
| + | **Не вижу кнопку «Создать объект».** |
| + | Кнопка доступна только пользователям с ролью «Редактор» и выше. Обратитесь к администратору аккаунта. |
| + | |
| + | **После сохранения объект не появляется на карте.** |
| + | Объект появится на карте после того, как трекер передаст первые координаты. Убедитесь, что трекер включен и настроен на сервер SKIF.PRO. |
| + | |
| + | ## Что дальше |
| + | - Настройте датчики объекта — см. статью «Карточка объекта — вкладка Датчики» |
| + | - Добавьте объект в группу — см. статью «Как добавить объект в группу» |
| + | ``` |
| + | |
| + | --- |
| + | |
| + | ### Тип B: Концепция (описание функциональности) |
| + | *Пары: `S2→R1`, `S2→R2`, `S4→R2`* |
| + | |
| + | **Когда создаётся:** нужно объяснить, *что* делает функция и *зачем*, прежде чем показывать *как*. |
| + | |
| + | **Признаки правильной статьи типа B:** |
| + | - Отвечает на вопрос «зачем это нужно» и «как это устроено», а не «как нажать» |
| + | - Описывает бизнес-логику и сценарии применения |
| + | - Может содержать схемы и диаграммы |
| + | - Не дублирует пошаговые инструкции — даёт ссылки на них |
| + | - Для R1 — аналогии и примеры из жизни, для R2 — логика системы и модели данных |
| + | |
| + | **Обязательная структура:** |
| + | |
| + | | Секция | Обязательность | Назначение | |
| + | |--------|:---:|---| |
| + | | `# [Название функциональности]` | ✅ обязательно | Для R1: «Что такое X в SKIF.PRO». Для R2: «X: модель данных и логика» | |
| + | | `## Для чего это нужно` | ✅ обязательно | Бизнес-задача языком получателя | |
| + | | `## Как это работает` | ✅ обязательно | Принцип работы. Для R1 — простым языком. Для R2 — техническая логика | |
| + | | `## Сценарии применения` | ✅ обязательно | 2–4 сценария использования | |
| + | | `## Ограничения и важные условия` | ✅ обязательно | Граничные случаи, зависимости от тарифа/настроек | |
| + | | `## Связанные инструкции` | 💡 рекомендуемо | Ссылки на статьи типа A | |
| + | |
| + | --- |
| + | |
| + | ### Тип C: Справочник интерфейса |
| + | *Пары: `S2→R1`, `S3→R1`* |
| + | |
| + | **Когда создаётся:** нужно описать конкретный экран, вкладку или форму — перечислить все поля с их назначением и допустимыми значениями. |
| + | |
| + | **Признаки правильной статьи типа C:** |
| + | - Привязана к одному конкретному экрану или вкладке (одна вкладка = одна статья) |
| + | - Перечисляет поля, их назначение, допустимые значения, значения по умолчанию |
| + | - Не учит «как», описывает «что» — пошаговые действия выносятся в тип A |
| + | - Содержит скриншот экрана с текстовым описанием |
| + | |
| + | **Обязательная структура:** |
| + | |
| + | | Секция | Обязательность | Назначение | |
| + | |--------|:---:|---| |
| + | | `# [Название экрана — вкладка/форма]` | ✅ обязательно | Точное название как в интерфейсе | |
| + | | `## Назначение` | ✅ обязательно | 1–2 предложения: для чего используется экран | |
| + | | `## Как открыть` | ✅ обязательно | Краткий путь навигации (без полной инструкции) | |
| + | | `## Описание полей` | ✅ обязательно | Таблица: поле, описание, допустимые значения, по умолчанию | |
| + | | `## Связанные инструкции` | 💡 рекомендуемо | Ссылки на статьи типа A, которые используют этот экран | |
| + | |
| + | **Пример:** |
| + | |
| + | ```markdown |
| + | # Карточка объекта — вкладка «Основные» |
| + | |
| + | ## Назначение |
| + | Вкладка содержит базовые параметры объекта мониторинга: название, тип, привязку к трекеру. |
| + | |
| + | ## Как открыть |
| + | **Объекты** → выберите объект → вкладка **Основные**. |
| + | |
| + | ## Описание полей |
| + | |
| + | | Поле | Описание | Допустимые значения | По умолчанию | |
| + | |------|----------|---------------------|--------------| |
| + | | **Название** | Отображаемое имя объекта на карте и в отчётах | Текст, до 100 символов | — | |
| + | | **IMEI** | Идентификатор трекера | 15 цифр | — | |
| + | | **Тип объекта** | Категория транспорта | Легковой, Грузовой, Спецтехника, Человек | Легковой | |
| + | | **Иконка** | Значок объекта на карте | Выбор из библиотеки | Автомобиль | |
| + | |
| + | ## Связанные инструкции |
| + | - Как создать объект — см. статью «Как добавить транспортное средство» |
| + | - Как изменить тип объекта — см. статью «Как редактировать объект» |
| + | ``` |
| + | |
| + | --- |
| + | |
| + | ### Тип D: Устранение неполадок (Troubleshooting) |
| + | *Пары: `S1→R1`, `S1→R2`, `S3→R2`* |
| + | |
| + | **Когда создаётся:** техподдержка или разработчики фиксируют повторяющиеся проблемы с решениями. |
| + | |
| + | **Признаки правильной статьи типа D:** |
| + | - Заголовок — описание симптома словами получателя, а не технической причиной |
| + | - Решения идут от простого к сложному |
| + | - Есть явный раздел «когда обращаться в поддержку» |
| + | - Для R2: допустимы технические детали (коды ошибок, логи, curl-примеры) |
| + | |
| + | **Обязательная структура:** |
| + | |
| + | | Секция | Обязательность | Назначение | |
| + | |--------|:---:|---| |
| + | | `# [Симптом словами получателя]` | ✅ обязательно | Для R1: «Трекер не выходит на связь». Для R2: «Запрос возвращает ошибку 502» | |
| + | | `## Симптом` | ✅ обязательно | Точное описание: что видит получатель | |
| + | | `## Возможные причины и решения` | ✅ обязательно | H3 для каждой причины: диагностика + решение | |
| + | | `## Если ничего не помогло` | ✅ обязательно | Что сообщить в поддержку, какие данные подготовить | |
| + | |
| + | **Пример для R1:** |
| + | |
| + | ```markdown |
| + | # Трекер не выходит на связь |
| + | |
| + | ## Симптом |
| + | Объект на карте отображается серым. В карточке объекта в поле **Последняя связь** указано время более 30 минут назад. |
| + | |
| + | ## Возможные причины и решения |
| + | |
| + | ### Причина 1: Трекер выключен или разряжен |
| + | Проверьте, горит ли индикатор питания на трекере. |
| + | **Решение:** Подключите трекер к питанию и дождитесь загрузки (1–3 минуты). |
| + | |
| + | ### Причина 2: Нет покрытия GSM-сети |
| + | Трекер находится в зоне без мобильной связи (подземная парковка, удалённая территория). |
| + | **Решение:** Переместите транспорт в зону покрытия. Данные передадутся автоматически. |
| + | |
| + | ## Если ничего не помогло |
| + | Обратитесь в техподдержку и сообщите: |
| + | - IMEI трекера |
| + | - Время последней связи из карточки объекта |
| + | - Какие шаги уже выполнены |
| + | ``` |
| + | |
| + | **Пример для R2:** |
| + | |
| + | ```markdown |
| + | # 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. Заголовки |
| + | |
| + | | Правило | Правильно | Неправильно | |
| + | |---------|-----------|-------------| |
| + | | Для инструкций (A) — начинать с глагола | «Как создать геозону» | «Геозоны. Создание» | |
| + | | Для концепций (B) — R1: «Что такое…»; R2: объект + контекст | «Что такое геозоны в SKIF.PRO» / «Геозоны: модель данных и ограничения» | «Введение в геозоны» | |
| + | | Для справочников (C) — название экрана | «Карточка объекта — вкладка Основные» | «Основные настройки объекта» | |
| + | | Для troubleshooting (D) — симптом словами получателя | «Почему трекер офлайн» | «Статус трекера» | |
| + | | Не использовать аббревиатуры без расшифровки | «Настройка CAN-шины (бортовой сети)» | «Настройка CAN» | |
| + | |
| + | ### 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):** допустимы, но обязательно маркируются: |
| + | |
| + | ```markdown |
| + | > 🔧 Техническая статья для интеграторов: [Протокол обмена данными с трекерами](ссылка) |
| + | ``` |
| + | |
| + | ```markdown |
| + | > 📱 Статья для пользователей: [Как добавить транспортное средство](ссылка) |
| + | ``` |
| + | |
| + | **Формат ссылок:** |
| + | - ✅ `см. статью «Как создать объект»` |
| + | - ❌ `см. здесь` |
| + | - ❌ `подробнее по ссылке` |
| + | |
| + | --- |
| + | |
| + | ## Часть 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): |
| + | |
| + | ```yaml |
| + | --- |
| + | 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. Шаблон задачи на документирование |
| + | |
| + | При постановке задачи на создание или обновление статьи инициатор заполняет: |
| + | |
| + | | Поле | Описание | Пример | |
| + | |------|----------|--------| |
| + | | **Триггер** | Что вызвало необходимость | «Добавлена фича X в релизе 2.5» | |
| + | | **Стейкхолдеры** | Источник → Получатель | `S2 → R1` | |
| + | | **Тип статьи** | A / B / C / D | A (Инструкция) | |
| + | | **Объём** | Какая функциональность покрывается | «Создание геозоны через UI» | |
| + | | **Эксперт для интервью** | Кто владеет знанием | «Иванов И.И., backend-разработчик» | |
| + | | **Дедлайн** | Когда нужна готовая статья | «До конца спринта 14» | |
| + | |
| + | --- |
| + | |
| + | ## Часть 7. Правила актуализации |
| + | |
| + | **Статья устаревает в момент, когда:** |
| + | - Изменился интерфейс или поведение функции |
| + | - Изменились бизнес-правила или логика работы |
| + | - Пользователи задают вопросы, ответы на которые должны быть в статье |
| + | |
| + | **Ответственность за актуализацию:** |
| + | |
| + | | Триггер | Кто обновляет | Срок | |
| + | |---------|--------------|------| |
| + | | Новый релиз с изменением фичи | Автор статьи (владелец) | В рамках спринта релиза | |
| + | | Сигнал от техподдержки (статья вводит в заблуждение) | Техписатель + владелец | Не позднее 2 рабочих дней | |
| + | | Плановая проверка | Технический писатель | Ежеквартально | |
| + | |
| + | **Признак «протухшей» документации:** пользователи или интеграторы задают вопросы, ответы на которые должны быть в статье. Если этот паттерн возникает — статья требует ревизии. |