Commit 292dbf
2026-03-10 12:10:03 GitLab Deploy: cleanup: remove test content before GitLab sync| objects.md .. /dev/null | |
| @@ 1,3 0,0 @@ | |
| - | # Объеты |
| - | |
| - | Объеты это |
| objects/справочник объектов.md .. /dev/null | |
| @@ 1,1 0,0 @@ | |
| - | # Справочник объектов |
| objects/справочник объектов/создание объекта.md .. /dev/null | |
| @@ 1,1 0,0 @@ | |
| - | # Создание объекта |
| objects/справочник объектов/создание объекта/удаление.md .. /dev/null | |
| @@ 1,2 0,0 @@ | |
| - | # Удаление |
| - |  |
| objects/справочник объектов/создание объекта/удаление/1024-2-removebg-preview.png .. /dev/null | |
| руководство по написанию технической документации.md .. /dev/null | |
| @@ 1,540 0,0 @@ | |
| - | # Руководство по написанию технической документации 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 рабочих дней | |
| - | | Плановая проверка | Технический писатель | Ежеквартально | |
| - | |
| - | **Признак «протухшей» документации:** пользователи или интеграторы задают вопросы, ответы на которые должны быть в статье. Если этот паттерн возникает — статья требует ревизии. |
| руководство по структурированию wiki skifpro.md .. /dev/null | |
| @@ 1,401 0,0 @@ | |
| - | # Руководство по структурированию Wiki SKIF.PRO |
| - | |
| - | > **Для кого:** авторы статей, технический писатель, менеджер документации, AI-агент проверки. |
| - | > |
| - | > **Цель:** единые правила организации Wiki — как определить раздел, подраздел и место конкретной статьи. |
| - | > |
| - | > **Связанные документы:** |
| - | > - `documentation-guidelines.md` — правила написания статей и обязательные структуры типов |
| - | > - `ai-checklist.md` — единый чек-лист для AI-агента проверки |
| - | |
| - | --- |
| - | |
| - | ## Часть 1. Архитектура Wiki: уровни иерархии |
| - | |
| - | Wiki SKIF.PRO строится по трёхуровневой модели: |
| - | |
| - | ``` |
| - | Раздел (уровень 1) |
| - | └── Подраздел (уровень 2) |
| - | └── Статья (уровень 3) |
| - | ``` |
| - | |
| - | **Правила уровней:** |
| - | |
| - | | Уровень | Что это | Пример | Содержит | |
| - | |---------|---------|--------|----------| |
| - | | **Раздел** | Крупный блок функциональности или аудитории | `Объекты`, `Геозоны`, `Отчёты` | 2–15 подразделов | |
| - | | **Подраздел** | Логическая группа статей одной темы | `Объекты / Справочник объектов` | 3–10 статей | |
| - | | **Статья** | Атомарная единица: одна задача или один экран | `Как создать объект` | Только контент | |
| - | |
| - | > ⚠️ **Запрещено:** создавать подраздел с одной статьёй. Если статья одна — она идёт напрямую в родительский раздел. |
| - | |
| - | --- |
| - | |
| - | ## Часть 2. Разделы верхнего уровня |
| - | |
| - | ### Принцип формирования разделов |
| - | |
| - | Разделы формируются по **функциональным доменам системы**, а не по типам статей. Неправильно делать разделы «Инструкции», «FAQ», «Справочники» — это смешивает аудитории и ломает навигацию. |
| - | |
| - | ### Правило разделения аудиторий (R1 vs R2) |
| - | |
| - | **Критический принцип:** статьи для конечных клиентов (R1) и интеграторов (R2) **никогда не смешиваются** в одном разделе. Аудитория определяет либо весь раздел целиком, либо подраздел внутри раздела. |
| - | |
| - | #### Стратегия 1: Раздельные разделы верхнего уровня (рекомендуется) |
| - | |
| - | Технические разделы для интеграторов выносятся отдельно: |
| - | |
| - | ``` |
| - | Wiki SKIF.PRO |
| - | ├── 📱 ДЛЯ ПОЛЬЗОВАТЕЛЕЙ (R1) |
| - | │ ├── Начало работы |
| - | │ ├── Объекты |
| - | │ ├── Геозоны |
| - | │ ├── Отчёты |
| - | │ ├── Уведомления |
| - | │ └── Мобильное приложение |
| - | │ |
| - | └── 🔧 ДЛЯ ИНТЕГРАТОРОВ (R2) |
| - | ├── Протоколы передачи данных |
| - | ├── Webhooks и события |
| - | ├── Импорт данных |
| - | └── Интеграция с 1С |
| - | ``` |
| - | |
| - | **Преимущества:** |
| - | - Пользователь сразу видит, что ему предназначено |
| - | - AI-агент легко фильтрует по аудитории |
| - | - Невозможно случайно попасть не в ту документацию |
| - | |
| - | > **Примечание:** API-документация ведётся в Postman (отдельный workflow) и не входит в структуру Wiki. |
| - | |
| - | #### Стратегия 2: Подразделы по аудитории (если домен пересекается) |
| - | |
| - | Если одна функциональность имеет и пользовательский, и интеграционный аспекты: |
| - | |
| - | ``` |
| - | Объекты/ |
| - | ├── 👤 Для пользователей/ |
| - | │ ├── [Концепция] Что такое объект в SKIF.PRO |
| - | │ ├── [Инструкция] Как создать объект |
| - | │ └── [Справочник] Карточка объекта — вкладка Основные |
| - | │ |
| - | └── 🔧 Для интеграторов/ |
| - | ├── [Концепция] Объекты: модель данных и ограничения |
| - | └── [Troubleshooting] Частые ошибки при импорте объектов |
| - | ``` |
| - | |
| - | **Когда использовать:** функция работает через UI (R1) И имеет интеграционные аспекты (R2). |
| - | |
| - | **Когда НЕ использовать:** если у функции есть только UI или только интеграция — тогда весь раздел относится к одной аудитории. |
| - | |
| - | ### Текущие разделы Wiki SKIF.PRO |
| - | |
| - | ``` |
| - | Wiki SKIF.PRO |
| - | │ |
| - | ├── 📱 ДЛЯ ПОЛЬЗОВАТЕЛЕЙ |
| - | │ ├── Начало работы ← Онбординг новых пользователей (R1) |
| - | │ ├── Объекты ← Работа с объектами через UI (R1) |
| - | │ ├── Геозоны ← Работа с геозонами (R1) |
| - | │ ├── Отчёты ← Построение и настройка отчётов (R1) |
| - | │ ├── Уведомления ← Настройка событий и оповещений (R1) |
| - | │ ├── Пользователи ← Управление аккаунтами и правами (R1) |
| - | │ ├── Мобильное приложение ← Документация мобильного клиента (R1) |
| - | │ ├── Администрирование ← Для администраторов аккаунта (R1) |
| - | │ └── Биллинг ← Тарифы, оплата, лицензии (R1) |
| - | │ |
| - | └── 🔧 ДЛЯ ИНТЕГРАТОРОВ |
| - | ├── Протоколы ← Протоколы передачи данных с трекеров (R2) |
| - | ├── Webhooks ← Настройка вебхуков и событий (R2) |
| - | ├── Импорт данных ← Массовый импорт (R2) |
| - | └── Интеграция с 1С ← Коннекторы для учётных систем (R2) |
| - | ``` |
| - | |
| - | > **Правило добавления нового раздела:** раздел создаётся, если в него можно поместить не менее 5 статей сразу. Иначе — статьи идут в смежный раздел или в «Начало работы». |
| - | |
| - | --- |
| - | |
| - | ## Часть 3. Структура подраздела |
| - | |
| - | Каждый подраздел строится по единой схеме. Пример для раздела **«Объекты»** (R1): |
| - | |
| - | ``` |
| - | Объекты/ |
| - | ├── [B — Концепция] Что такое объект в SKIF.PRO |
| - | ├── Справочник объектов/ |
| - | │ ├── [C — Справочник] Обзор справочника объектов |
| - | │ ├── [A — Инструкция] Как найти объект |
| - | │ ├── [A — Инструкция] Как создать объект |
| - | │ ├── [A — Инструкция] Как редактировать объект |
| - | │ └── [A — Инструкция] Как удалить объект |
| - | ├── Карточка объекта/ |
| - | │ ├── [C — Справочник] Вкладка «Основные» |
| - | │ ├── [C — Справочник] Вкладка «Датчики» |
| - | │ ├── [C — Справочник] Вкладка «Сцепки» |
| - | │ ├── [C — Справочник] Вкладка «Смены» |
| - | │ ├── [C — Справочник] Вкладка «ТО» |
| - | │ └── [C — Справочник] Вкладка «Тех. параметры» |
| - | ├── Группы объектов/ |
| - | │ ├── [B — Концепция] Что такое группы объектов |
| - | │ ├── [A — Инструкция] Как создать группу |
| - | │ └── [A — Инструкция] Как добавить объект в группу |
| - | └── [D — Troubleshooting] Частые проблемы с объектами |
| - | ``` |
| - | |
| - | Пример для раздела **«Протоколы»** (R2): |
| - | |
| - | ``` |
| - | Протоколы/ |
| - | ├── [B — Концепция] Как устроена передача данных с трекеров |
| - | ├── [B — Концепция] Поддерживаемые протоколы: обзор |
| - | ├── Wialon IPS/ |
| - | │ ├── [B — Концепция] Wialon IPS: структура пакетов и логика обмена |
| - | │ ├── [C — Справочник] Wialon IPS: формат сообщений и типы данных |
| - | │ └── [D — Troubleshooting] Данные не поступают по Wialon IPS |
| - | └── EGTS/ |
| - | ├── [B — Концепция] EGTS: структура и особенности |
| - | ├── [C — Справочник] EGTS: формат сообщений |
| - | └── [D — Troubleshooting] Ошибки при подключении по EGTS |
| - | ``` |
| - | |
| - | > **Примечание:** для R2-разделов тип C (Справочник) описывает не экран интерфейса, а формат данных, структуру сообщений, таблицу параметров — аналогичная функция «перечислить поля и их значения», но для технического контекста. |
| - | |
| - | ### Правило порядка статей внутри подраздела |
| - | |
| - | 1. **Концепция (B)** — всегда **первая** |
| - | 2. **Обзор интерфейса / формата (C)** — **вторая** (если есть) |
| - | 3. **Инструкции (A)** — от простого к сложному: создание → редактирование → удаление |
| - | 4. **Справочники полей (C)** — после инструкций |
| - | 5. **Troubleshooting (D)** — всегда **последний** |
| - | |
| - | --- |
| - | |
| - | ## Часть 4. Четыре типа статей и их место в структуре |
| - | |
| - | Каждая статья принадлежит одному из четырёх типов. Тип определяет, **куда она попадает** в иерархии. |
| - | |
| - | > **Полные обязательные структуры, шаблоны и примеры** каждого типа описаны в `documentation-guidelines.md`, Часть 2. |
| - | |
| - | ### Тип A: Инструкция — как сделать |
| - | |
| - | **Аудитория:** R1. |
| - | **Место в структуре:** основное тело подраздела, после концепции и обзора. |
| - | **Признак:** отвечает на вопрос «как сделать X?», содержит пронумерованные шаги, один конкретный результат. |
| - | **Одна задача = одна инструкция.** Нельзя объединять «создание» и «редактирование» в одну статью. |
| - | |
| - | ``` |
| - | Примеры заголовков: |
| - | ✓ «Как создать объект» |
| - | ✓ «Как настроить уведомление о выезде из геозоны» |
| - | ✗ «Создание и редактирование объектов» |
| - | ✗ «Работа с объектами» |
| - | ``` |
| - | |
| - | ### Тип B: Концепция — что это и зачем |
| - | |
| - | **Аудитория:** R1 или R2. |
| - | **Место в структуре:** первая статья подраздела или раздела. |
| - | **Признак:** отвечает на вопрос «что это?» и «зачем нужно?», не содержит пошаговых инструкций. |
| - | **Одна на подраздел.** Не создавать несколько концептуальных статей об одном домене для одной аудитории. |
| - | |
| - | ``` |
| - | Примеры заголовков: |
| - | Для R1: |
| - | ✓ «Что такое объект в SKIF.PRO» |
| - | ✓ «Как устроены права доступа» |
| - | ✗ «Введение в раздел объектов» |
| - | ✗ «Объекты — общая информация» |
| - | |
| - | Для R2: |
| - | ✓ «Объекты: модель данных и ограничения» |
| - | ✓ «Как устроена передача данных с трекеров» |
| - | ✗ «Общие сведения о протоколах» |
| - | ``` |
| - | |
| - | ### Тип C: Справочник — описание полей, параметров, формата |
| - | |
| - | **Аудитория:** R1 или R2. |
| - | **Место в структуре:** после инструкций. Описывает конкретный экран, форму или формат данных. |
| - | **Признак:** перечисляет поля/параметры, их назначение, допустимые значения. Не учит «как», описывает «что». |
| - | **Привязан к конкретному объекту.** Для R1: одна вкладка или форма = одна статья. Для R2: один формат/протокол = одна статья. |
| - | |
| - | ``` |
| - | Примеры заголовков: |
| - | Для R1: |
| - | ✓ «Карточка объекта — вкладка Основные» |
| - | ✓ «Форма создания геозоны: описание полей» |
| - | ✗ «Поля объекта» |
| - | ✗ «Настройки» |
| - | |
| - | Для R2: |
| - | ✓ «Wialon IPS: формат сообщений и типы данных» |
| - | ✓ «Формат данных объекта при импорте» |
| - | ✗ «Данные» |
| - | ✗ «Параметры» |
| - | ``` |
| - | |
| - | ### Тип D: Troubleshooting — решение проблем |
| - | |
| - | **Аудитория:** R1 или R2. |
| - | **Место в структуре:** всегда **последняя** статья подраздела. |
| - | **Признак:** заголовок — симптом словами получателя, решения от простого к сложному. |
| - | |
| - | ``` |
| - | Примеры заголовков: |
| - | Для R1: |
| - | ✓ «Трекер не выходит на связь» |
| - | ✓ «Отчёт показывает 0 км» |
| - | ✗ «Ошибка соединения с устройством» |
| - | ✗ «Проблемы с расчётом пробега» |
| - | |
| - | Для R2: |
| - | ✓ «Webhook не доставляет события» |
| - | ✓ «Данные не поступают по Wialon IPS» |
| - | ✗ «Ошибка HTTP 502» |
| - | ✗ «Проблемы с протоколом» |
| - | ``` |
| - | |
| - | --- |
| - | |
| - | ## Часть 5. Алгоритм определения места статьи |
| - | |
| - | Используйте этот алгоритм при создании каждой новой статьи: |
| - | |
| - | ``` |
| - | ШАГ 1. Определите аудиторию и функциональный домен |
| - | → Кто читатель: R1 (конечный клиент) или R2 (интегратор)? |
| - | → К какой области относится: UI / интеграция / и то и другое? |
| - | |
| - | Если R1 (клиент): |
| - | → Раздел из блока «ДЛЯ ПОЛЬЗОВАТЕЛЕЙ» |
| - | |
| - | Если R2 (интегратор): |
| - | → Раздел из блока «ДЛЯ ИНТЕГРАТОРОВ» |
| - | |
| - | Если домен пересекается (есть и UI, и интеграция): |
| - | → Основной раздел + подраздел по аудитории |
| - | |
| - | ШАГ 2. Определите тип статьи |
| - | Что делает эта статья? |
| - | → Объясняет «что это» и «зачем» → B (Концепция) |
| - | → Учит «как сделать» → A (Инструкция) |
| - | → Описывает экран / поля / формат → C (Справочник) |
| - | → Решает проблему → D (Troubleshooting) |
| - | |
| - | ШАГ 3. Определите подраздел |
| - | → Есть ли уже подраздел для этой темы? |
| - | ДА → статья идёт туда |
| - | НЕТ → создать подраздел (только если туда войдёт 3+ статьи) |
| - | или разместить статью напрямую в раздел |
| - | |
| - | ШАГ 4. Определите позицию внутри подраздела |
| - | → Концепция (B) → первая |
| - | → Обзор / Справочник (C) → после концепции |
| - | → Инструкции (A) → по сложности |
| - | → Справочники полей (C) → после инструкций |
| - | → Troubleshooting (D) → последняя |
| - | ``` |
| - | |
| - | --- |
| - | |
| - | ## Часть 6. Правила именования |
| - | |
| - | ### Разделы и подразделы (существительные) |
| - | |
| - | | Правильно | Неправильно | |
| - | |-----------|-------------| |
| - | | `Объекты` | `Работа с объектами` | |
| - | | `Справочник объектов` | `Список объектов и как с ними работать` | |
| - | | `Карточка объекта` | `Форма редактирования/создания объекта` | |
| - | |
| - | ### Статьи типа B — Концепции |
| - | |
| - | **Для R1:** «Что такое…» или «Как устроен(а/ы)…» |
| - | **Для R2:** объект + контекст (модель данных, структура, логика) |
| - | |
| - | | Правильно | Неправильно | |
| - | |-----------|-------------| |
| - | | `Что такое объект в SKIF.PRO` (R1) | `Объекты. Введение` | |
| - | | `Объекты: модель данных и ограничения` (R2) | `Общие сведения` | |
| - | | `Как устроены права доступа` (R1) | `Права доступа` | |
| - | |
| - | ### Статьи типа A — Инструкции (глагол «Как» + действие) |
| - | |
| - | | Правильно | Неправильно | |
| - | |-----------|-------------| |
| - | | `Как создать объект` | `Создание объекта` | |
| - | | `Как настроить уведомление` | `Настройка уведомлений` | |
| - | | `Как найти объект по IMEI` | `Поиск объектов` | |
| - | |
| - | ### Статьи типа C — Справочники |
| - | |
| - | **Для R1:** название экрана + вкладка/форма |
| - | **Для R2:** название формата/протокола + «формат сообщений» / «типы данных» |
| - | |
| - | | Правильно | Неправильно | |
| - | |-----------|-------------| |
| - | | `Карточка объекта — вкладка Основные` (R1) | `Основные настройки объекта` | |
| - | | `Справочник объектов — обзор интерфейса` (R1) | `Интерфейс справочника` | |
| - | | `Wialon IPS: формат сообщений и типы данных` (R2) | `Данные Wialon` | |
| - | |
| - | ### Статьи типа D — Troubleshooting (симптом словами получателя) |
| - | |
| - | | Правильно | Неправильно | |
| - | |-----------|-------------| |
| - | | `Трекер не выходит на связь` (R1) | `Ошибка соединения с устройством` | |
| - | | `Отчёт показывает 0 км` (R1) | `Проблемы с расчётом пробега` | |
| - | | `Webhook не доставляет события` (R2) | `Ошибка HTTP 502` | |
| - | |
| - | --- |
| - | |
| - | ## Часть 7. Антипаттерны структуры |
| - | |
| - | ### ❌ «Свалка» — один раздел для всего |
| - | |
| - | ``` |
| - | Объекты/ |
| - | ├── Объекты — всё о них ← нарушение атомарности |
| - | ├── FAQ по объектам ← FAQ-солянка |
| - | └── Разное ← недопустимо |
| - | ``` |
| - | |
| - | ### ❌ Смешение аудиторий в одном разделе |
| - | |
| - | ``` |
| - | Протоколы/ |
| - | ├── Как устроена передача данных ← R2 |
| - | ├── Wialon IPS: формат сообщений ← R2 |
| - | ├── Как добавить трекер через интерфейс ← R1 (НЕПРАВИЛЬНО!) |
| - | └── Частые ошибки подключения ← R2 |
| - | ``` |
| - | |
| - | **Почему плохо:** |
| - | - R1 (клиент) зашёл в «Протоколы» и видит инструкции для UI — путаница |
| - | - AI-агент не может отфильтровать контент по аудитории |
| - | - Нарушается принцип «раздел = одна аудитория» |
| - | |
| - | **Правильно:** UI-инструкции в раздел «Объекты» (R1), протоколы в раздел «Протоколы» (R2) |
| - | |
| - | ### ❌ Дублирование статей в разных разделах |
| - | |
| - | Одна и та же инструкция не может находиться в двух местах. Если тема пересекается — используйте **ссылки**, а не копирование контента. |
| - | |
| - | ### ❌ Разделы без концептуальной статьи |
| - | |
| - | Каждый раздел и значимый подраздел (3+ статьи) должен иметь хотя бы одну концептуальную статью (тип B), объясняющую назначение раздела. |
| - | |
| - | ### ❌ Инструкция и справочник в одной статье |
| - | |
| - | ``` |
| - | ❌ «Как создать объект» — и здесь же таблица с описанием всех полей |
| - | ✓ «Как создать объект» → ссылка на «Карточка объекта — вкладка Основные» |
| - | ``` |
| - | |
| - | ### ❌ Перекрёстные ссылки R1↔R2 без маркировки |
| - | |
| - | ``` |
| - | ❌ См. статью «Протокол обмена данными с трекерами» |
| - | ✓ > 🔧 Техническая статья для интеграторов: «Протокол обмена данными с трекерами» |
| - | ``` |
