Commit 83a2bc
2026-02-18 14:34:37 Dima: 123214| /dev/null .. руководство по структурированию wiki skifpro.md | |
| @@ 0,0 1,401 @@ | |
| + | # Руководство по структурированию 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 без маркировки |
| + | |
| + | ``` |
| + | ❌ См. статью «Протокол обмена данными с трекерами» |
| + | ✓ > 🔧 Техническая статья для интеграторов: «Протокол обмена данными с трекерами» |
| + | ``` |