Page Index

Blame

83a2bc Dima 2026-02-18 14:34:37
123214
1 
# Руководство по структурированию Wiki SKIF.PRO
2
3
> **Для кого:** авторы статей, технический писатель, менеджер документации, AI-агент проверки.
4
>
5
> **Цель:** единые правила организации Wiki — как определить раздел, подраздел и место конкретной статьи.
6
>
7
> **Связанные документы:**
8
> - `documentation-guidelines.md` — правила написания статей и обязательные структуры типов
9
> - `ai-checklist.md` — единый чек-лист для AI-агента проверки
10
11
---
12
13
## Часть 1. Архитектура Wiki: уровни иерархии
14
15
Wiki SKIF.PRO строится по трёхуровневой модели:
16
17
```
18
Раздел (уровень 1)
19
└── Подраздел (уровень 2)
20
└── Статья (уровень 3)
21
```
22
23
**Правила уровней:**
24
25
| Уровень | Что это | Пример | Содержит |
26
|---------|---------|--------|----------|
27
| **Раздел** | Крупный блок функциональности или аудитории | `Объекты`, `Геозоны`, `Отчёты` | 2–15 подразделов |
28
| **Подраздел** | Логическая группа статей одной темы | `Объекты / Справочник объектов` | 3–10 статей |
29
| **Статья** | Атомарная единица: одна задача или один экран | `Как создать объект` | Только контент |
30
31
> ⚠️ **Запрещено:** создавать подраздел с одной статьёй. Если статья одна — она идёт напрямую в родительский раздел.
32
33
---
34
35
## Часть 2. Разделы верхнего уровня
36
37
### Принцип формирования разделов
38
39
Разделы формируются по **функциональным доменам системы**, а не по типам статей. Неправильно делать разделы «Инструкции», «FAQ», «Справочники» — это смешивает аудитории и ломает навигацию.
40
41
### Правило разделения аудиторий (R1 vs R2)
42
43
**Критический принцип:** статьи для конечных клиентов (R1) и интеграторов (R2) **никогда не смешиваются** в одном разделе. Аудитория определяет либо весь раздел целиком, либо подраздел внутри раздела.
44
45
#### Стратегия 1: Раздельные разделы верхнего уровня (рекомендуется)
46
47
Технические разделы для интеграторов выносятся отдельно:
48
49
```
50
Wiki SKIF.PRO
51
├── 📱 ДЛЯ ПОЛЬЗОВАТЕЛЕЙ (R1)
52
│ ├── Начало работы
53
│ ├── Объекты
54
│ ├── Геозоны
55
│ ├── Отчёты
56
│ ├── Уведомления
57
│ └── Мобильное приложение
58
│
59
└── 🔧 ДЛЯ ИНТЕГРАТОРОВ (R2)
60
├── Протоколы передачи данных
61
├── Webhooks и события
62
├── Импорт данных
63
└── Интеграция с 1С
64
```
65
66
**Преимущества:**
67
- Пользователь сразу видит, что ему предназначено
68
- AI-агент легко фильтрует по аудитории
69
- Невозможно случайно попасть не в ту документацию
70
71
> **Примечание:** API-документация ведётся в Postman (отдельный workflow) и не входит в структуру Wiki.
72
73
#### Стратегия 2: Подразделы по аудитории (если домен пересекается)
74
75
Если одна функциональность имеет и пользовательский, и интеграционный аспекты:
76
77
```
78
Объекты/
79
├── 👤 Для пользователей/
80
│ ├── [Концепция] Что такое объект в SKIF.PRO
81
│ ├── [Инструкция] Как создать объект
82
│ └── [Справочник] Карточка объекта — вкладка Основные
83
│
84
└── 🔧 Для интеграторов/
85
├── [Концепция] Объекты: модель данных и ограничения
86
└── [Troubleshooting] Частые ошибки при импорте объектов
87
```
88
89
**Когда использовать:** функция работает через UI (R1) И имеет интеграционные аспекты (R2).
90
91
**Когда НЕ использовать:** если у функции есть только UI или только интеграция — тогда весь раздел относится к одной аудитории.
92
93
### Текущие разделы Wiki SKIF.PRO
94
95
```
96
Wiki SKIF.PRO
97
│
98
├── 📱 ДЛЯ ПОЛЬЗОВАТЕЛЕЙ
99
│ ├── Начало работы ← Онбординг новых пользователей (R1)
100
│ ├── Объекты ← Работа с объектами через UI (R1)
101
│ ├── Геозоны ← Работа с геозонами (R1)
102
│ ├── Отчёты ← Построение и настройка отчётов (R1)
103
│ ├── Уведомления ← Настройка событий и оповещений (R1)
104
│ ├── Пользователи ← Управление аккаунтами и правами (R1)
105
│ ├── Мобильное приложение ← Документация мобильного клиента (R1)
106
│ ├── Администрирование ← Для администраторов аккаунта (R1)
107
│ └── Биллинг ← Тарифы, оплата, лицензии (R1)
108
│
109
└── 🔧 ДЛЯ ИНТЕГРАТОРОВ
110
├── Протоколы ← Протоколы передачи данных с трекеров (R2)
111
├── Webhooks ← Настройка вебхуков и событий (R2)
112
├── Импорт данных ← Массовый импорт (R2)
113
└── Интеграция с 1С ← Коннекторы для учётных систем (R2)
114
```
115
116
> **Правило добавления нового раздела:** раздел создаётся, если в него можно поместить не менее 5 статей сразу. Иначе — статьи идут в смежный раздел или в «Начало работы».
117
118
---
119
120
## Часть 3. Структура подраздела
121
122
Каждый подраздел строится по единой схеме. Пример для раздела **«Объекты»** (R1):
123
124
```
125
Объекты/
126
├── [B — Концепция] Что такое объект в SKIF.PRO
127
├── Справочник объектов/
128
│ ├── [C — Справочник] Обзор справочника объектов
129
│ ├── [A — Инструкция] Как найти объект
130
│ ├── [A — Инструкция] Как создать объект
131
│ ├── [A — Инструкция] Как редактировать объект
132
│ └── [A — Инструкция] Как удалить объект
133
├── Карточка объекта/
134
│ ├── [C — Справочник] Вкладка «Основные»
135
│ ├── [C — Справочник] Вкладка «Датчики»
136
│ ├── [C — Справочник] Вкладка «Сцепки»
137
│ ├── [C — Справочник] Вкладка «Смены»
138
│ ├── [C — Справочник] Вкладка «ТО»
139
│ └── [C — Справочник] Вкладка «Тех. параметры»
140
├── Группы объектов/
141
│ ├── [B — Концепция] Что такое группы объектов
142
│ ├── [A — Инструкция] Как создать группу
143
│ └── [A — Инструкция] Как добавить объект в группу
144
└── [D — Troubleshooting] Частые проблемы с объектами
145
```
146
147
Пример для раздела **«Протоколы»** (R2):
148
149
```
150
Протоколы/
151
├── [B — Концепция] Как устроена передача данных с трекеров
152
├── [B — Концепция] Поддерживаемые протоколы: обзор
153
├── Wialon IPS/
154
│ ├── [B — Концепция] Wialon IPS: структура пакетов и логика обмена
155
│ ├── [C — Справочник] Wialon IPS: формат сообщений и типы данных
156
│ └── [D — Troubleshooting] Данные не поступают по Wialon IPS
157
└── EGTS/
158
├── [B — Концепция] EGTS: структура и особенности
159
├── [C — Справочник] EGTS: формат сообщений
160
└── [D — Troubleshooting] Ошибки при подключении по EGTS
161
```
162
163
> **Примечание:** для R2-разделов тип C (Справочник) описывает не экран интерфейса, а формат данных, структуру сообщений, таблицу параметров — аналогичная функция «перечислить поля и их значения», но для технического контекста.
164
165
### Правило порядка статей внутри подраздела
166
167
1. **Концепция (B)** — всегда **первая**
168
2. **Обзор интерфейса / формата (C)** — **вторая** (если есть)
169
3. **Инструкции (A)** — от простого к сложному: создание → редактирование → удаление
170
4. **Справочники полей (C)** — после инструкций
171
5. **Troubleshooting (D)** — всегда **последний**
172
173
---
174
175
## Часть 4. Четыре типа статей и их место в структуре
176
177
Каждая статья принадлежит одному из четырёх типов. Тип определяет, **куда она попадает** в иерархии.
178
179
> **Полные обязательные структуры, шаблоны и примеры** каждого типа описаны в `documentation-guidelines.md`, Часть 2.
180
181
### Тип A: Инструкция — как сделать
182
183
**Аудитория:** R1.
184
**Место в структуре:** основное тело подраздела, после концепции и обзора.
185
**Признак:** отвечает на вопрос «как сделать X?», содержит пронумерованные шаги, один конкретный результат.
186
**Одна задача = одна инструкция.** Нельзя объединять «создание» и «редактирование» в одну статью.
187
188
```
189
Примеры заголовков:
190
✓ «Как создать объект»
191
✓ «Как настроить уведомление о выезде из геозоны»
192
✗ «Создание и редактирование объектов»
193
✗ «Работа с объектами»
194
```
195
196
### Тип B: Концепция — что это и зачем
197
198
**Аудитория:** R1 или R2.
199
**Место в структуре:** первая статья подраздела или раздела.
200
**Признак:** отвечает на вопрос «что это?» и «зачем нужно?», не содержит пошаговых инструкций.
201
**Одна на подраздел.** Не создавать несколько концептуальных статей об одном домене для одной аудитории.
202
203
```
204
Примеры заголовков:
205
Для R1:
206
✓ «Что такое объект в SKIF.PRO»
207
✓ «Как устроены права доступа»
208
✗ «Введение в раздел объектов»
209
✗ «Объекты — общая информация»
210
211
Для R2:
212
✓ «Объекты: модель данных и ограничения»
213
✓ «Как устроена передача данных с трекеров»
214
✗ «Общие сведения о протоколах»
215
```
216
217
### Тип C: Справочник — описание полей, параметров, формата
218
219
**Аудитория:** R1 или R2.
220
**Место в структуре:** после инструкций. Описывает конкретный экран, форму или формат данных.
221
**Признак:** перечисляет поля/параметры, их назначение, допустимые значения. Не учит «как», описывает «что».
222
**Привязан к конкретному объекту.** Для R1: одна вкладка или форма = одна статья. Для R2: один формат/протокол = одна статья.
223
224
```
225
Примеры заголовков:
226
Для R1:
227
✓ «Карточка объекта — вкладка Основные»
228
✓ «Форма создания геозоны: описание полей»
229
✗ «Поля объекта»
230
✗ «Настройки»
231
232
Для R2:
233
✓ «Wialon IPS: формат сообщений и типы данных»
234
✓ «Формат данных объекта при импорте»
235
✗ «Данные»
236
✗ «Параметры»
237
```
238
239
### Тип D: Troubleshooting — решение проблем
240
241
**Аудитория:** R1 или R2.
242
**Место в структуре:** всегда **последняя** статья подраздела.
243
**Признак:** заголовок — симптом словами получателя, решения от простого к сложному.
244
245
```
246
Примеры заголовков:
247
Для R1:
248
✓ «Трекер не выходит на связь»
249
✓ «Отчёт показывает 0 км»
250
✗ «Ошибка соединения с устройством»
251
✗ «Проблемы с расчётом пробега»
252
253
Для R2:
254
✓ «Webhook не доставляет события»
255
✓ «Данные не поступают по Wialon IPS»
256
✗ «Ошибка HTTP 502»
257
✗ «Проблемы с протоколом»
258
```
259
260
---
261
262
## Часть 5. Алгоритм определения места статьи
263
264
Используйте этот алгоритм при создании каждой новой статьи:
265
266
```
267
ШАГ 1. Определите аудиторию и функциональный домен
268
→ Кто читатель: R1 (конечный клиент) или R2 (интегратор)?
269
→ К какой области относится: UI / интеграция / и то и другое?
270
271
Если R1 (клиент):
272
→ Раздел из блока «ДЛЯ ПОЛЬЗОВАТЕЛЕЙ»
273
274
Если R2 (интегратор):
275
→ Раздел из блока «ДЛЯ ИНТЕГРАТОРОВ»
276
277
Если домен пересекается (есть и UI, и интеграция):
278
→ Основной раздел + подраздел по аудитории
279
280
ШАГ 2. Определите тип статьи
281
Что делает эта статья?
282
→ Объясняет «что это» и «зачем» → B (Концепция)
283
→ Учит «как сделать» → A (Инструкция)
284
→ Описывает экран / поля / формат → C (Справочник)
285
→ Решает проблему → D (Troubleshooting)
286
287
ШАГ 3. Определите подраздел
288
→ Есть ли уже подраздел для этой темы?
289
ДА → статья идёт туда
290
НЕТ → создать подраздел (только если туда войдёт 3+ статьи)
291
или разместить статью напрямую в раздел
292
293
ШАГ 4. Определите позицию внутри подраздела
294
→ Концепция (B) → первая
295
→ Обзор / Справочник (C) → после концепции
296
→ Инструкции (A) → по сложности
297
→ Справочники полей (C) → после инструкций
298
→ Troubleshooting (D) → последняя
299
```
300
301
---
302
303
## Часть 6. Правила именования
304
305
### Разделы и подразделы (существительные)
306
307
| Правильно | Неправильно |
308
|-----------|-------------|
309
| `Объекты` | `Работа с объектами` |
310
| `Справочник объектов` | `Список объектов и как с ними работать` |
311
| `Карточка объекта` | `Форма редактирования/создания объекта` |
312
313
### Статьи типа B — Концепции
314
315
**Для R1:** «Что такое…» или «Как устроен(а/ы)…»
316
**Для R2:** объект + контекст (модель данных, структура, логика)
317
318
| Правильно | Неправильно |
319
|-----------|-------------|
320
| `Что такое объект в SKIF.PRO` (R1) | `Объекты. Введение` |
321
| `Объекты: модель данных и ограничения` (R2) | `Общие сведения` |
322
| `Как устроены права доступа` (R1) | `Права доступа` |
323
324
### Статьи типа A — Инструкции (глагол «Как» + действие)
325
326
| Правильно | Неправильно |
327
|-----------|-------------|
328
| `Как создать объект` | `Создание объекта` |
329
| `Как настроить уведомление` | `Настройка уведомлений` |
330
| `Как найти объект по IMEI` | `Поиск объектов` |
331
332
### Статьи типа C — Справочники
333
334
**Для R1:** название экрана + вкладка/форма
335
**Для R2:** название формата/протокола + «формат сообщений» / «типы данных»
336
337
| Правильно | Неправильно |
338
|-----------|-------------|
339
| `Карточка объекта — вкладка Основные` (R1) | `Основные настройки объекта` |
340
| `Справочник объектов — обзор интерфейса` (R1) | `Интерфейс справочника` |
341
| `Wialon IPS: формат сообщений и типы данных` (R2) | `Данные Wialon` |
342
343
### Статьи типа D — Troubleshooting (симптом словами получателя)
344
345
| Правильно | Неправильно |
346
|-----------|-------------|
347
| `Трекер не выходит на связь` (R1) | `Ошибка соединения с устройством` |
348
| `Отчёт показывает 0 км` (R1) | `Проблемы с расчётом пробега` |
349
| `Webhook не доставляет события` (R2) | `Ошибка HTTP 502` |
350
351
---
352
353
## Часть 7. Антипаттерны структуры
354
355
### ❌ «Свалка» — один раздел для всего
356
357
```
358
Объекты/
359
├── Объекты — всё о них ← нарушение атомарности
360
├── FAQ по объектам ← FAQ-солянка
361
└── Разное ← недопустимо
362
```
363
364
### ❌ Смешение аудиторий в одном разделе
365
366
```
367
Протоколы/
368
├── Как устроена передача данных ← R2
369
├── Wialon IPS: формат сообщений ← R2
370
├── Как добавить трекер через интерфейс ← R1 (НЕПРАВИЛЬНО!)
371
└── Частые ошибки подключения ← R2
372
```
373
374
**Почему плохо:**
375
- R1 (клиент) зашёл в «Протоколы» и видит инструкции для UI — путаница
376
- AI-агент не может отфильтровать контент по аудитории
377
- Нарушается принцип «раздел = одна аудитория»
378
379
**Правильно:** UI-инструкции в раздел «Объекты» (R1), протоколы в раздел «Протоколы» (R2)
380
381
### ❌ Дублирование статей в разных разделах
382
383
Одна и та же инструкция не может находиться в двух местах. Если тема пересекается — используйте **ссылки**, а не копирование контента.
384
385
### ❌ Разделы без концептуальной статьи
386
387
Каждый раздел и значимый подраздел (3+ статьи) должен иметь хотя бы одну концептуальную статью (тип B), объясняющую назначение раздела.
388
389
### ❌ Инструкция и справочник в одной статье
390
391
```
392
❌ «Как создать объект» — и здесь же таблица с описанием всех полей
393
✓ «Как создать объект» → ссылка на «Карточка объекта — вкладка Основные»
394
```
395
396
### ❌ Перекрёстные ссылки R1↔R2 без маркировки
397
398
```
399
❌ См. статью «Протокол обмена данными с трекерами»
400
✓ > 🔧 Техническая статья для интеграторов: «Протокол обмена данными с трекерами»
401
```