🧱 Структура документации: принцип перевёрнутой пирамиды

Бывает, открываешь документацию — и вроде там всё есть, но что с ней делать — неясно. Читаешь страницу за страницей, а ответа на свой вопрос так и не находишь.
Проблема часто не в содержании, а в структуре.

⛓ Об общего — к частному

Это не про то, что в документации должно быть три раздела. Это про то, в каком порядке информация появляется перед читателем, чтобы ему не приходилось продираться через дебри деталей ради понимания сути.

👍 Верхушка пирамиды — самое важное

Сюда попадает то, что должен знать абсолютно каждый читатель:
- Что это такое — простыми словами
- Зачем нужно — какие проблемы решает
- Для кого предназначено — кто целевой пользователь
- В чём главная ценность — почему стоит использовать

Если этого нет в начале — дальше можно не читать. Никто не любит разбираться в тексте, который даже не объяснил, почему он вообще существует.

Тест верхушки: Человек, прочитавший только первый экран текста, должен понимать, стоит ли ему читать дальше.

✌️ Середина пирамиды — контекст и принципы

Если читатель остался, ему нужно понять, как это работает в общих чертах:
- Архитектура системы
- Основные сценарии использования
- Ключевые концепции и компоненты
- Взаимодействие элементов

Это необходимый контекст, без которого дальнейшие шаги превращаются в магические заклинания, а параметры — в набор случайных букв.

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

🖖 Нижний слой — детали и инструкции

Сюда входят технические подробности, которые ищут по конкретному вопросу:
- Как сделать конкретную задачу
- Что значит этот параметр или настройка
- Какие коды ошибок могут возникнуть
- Что делать, если что-то пошло не так

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

Тест нижнего слоя: Читатель должен легко находить ответ на конкретный вопрос через поиск или навигацию.


👜 Как это влияет на структуру документа?

Не обязательно физически делить документацию на три части. Важно, чтобы логика подачи информации двигалась от общего к частному, от контекста к деталям. И внутри всего документа, и в каждой статье, и в каждом блоке. Сначала — общий концепт, вводная часть*, потом уже детали.


🦖 Почему это жизненно важно

Потому что человек не готов сразу читать параметры и инструкции. Он сначала хочет убедиться, что не тратит время зря. И если порядок сломан, он не будет разбираться — он просто уйдёт.

Пирамида — это не только стиль. Это проявление уважения к читателю.

Вы даёте ему шанс быстро понять, в ту ли он вообще попал статью, и стоит ли углубляться дальше.


———
🪲 Проверьте свою документацию:

- Первый абзац отвечает на вопрос что это и зачем?
- Можно ли понять основную идею за 30 секунд?
- Детали появляются только после объяснения концепций?
- Читатель видит общую картину до погружения в нюансы?

Если хотя бы на один вопрос ответ «нет» — пора перестраивать пирамиду.

———
*с вводной тоже можно пережестить и высасывать из пальца о чём оно и для кого, поэтому я не о шаблоне говорю, а только о логике подачи

🌈 Кому мы вообще это пишем?

Сегодня — про аудиторию. Потому что если вы не знаете, кто будет читать, никакая структура, гайд и стиль не помогут.

Один документ — не для всех

Частая ошибка: написать «одну универсальную статью» для всех. В итоге получаем предсказуемый результат:
- Новичкам слишком сложно
- Опытным пользователям скучно
- Поддержке не хватает деталей

Разные люди приходят в документацию с разными задачами и ожиданиями. И каждому нужно своё.

Типичные аудитории технической документации

🌈 Новички
- Ищут базовые объяснения и пошаговые гайды
- Нуждаются в контексте и обосновании («почему это важно»)
- Ценят простые метафоры и наглядные примеры
- Часто читают документацию линейно, от начала до конца

🌈 Опытные пользователи
- Используют документацию как справочник
- Им нужно быстро найти конкретное решение
- Ценят точность и лаконичность
- Примеры кода для них — скорее подстраховка, чем обязательный элемент

🌈 Интеграторы
- Фокусируются на взаимодействии между системами
- Изучают API, архитектурные схемы, процессы авторизации
- Интересуются граничными случаями и нестандартными сценариями
- Ищут детальные спецификации и ограничения

🌈 Техническая поддержка
- Им важно понять, почему система сломалась и как это исправить
- Нуждаются в описании ошибок, кодов и методов диагностики
- Ценят раздел с обходными решениями (workarounds)
- Часто используют документацию во время общения с клиентом

Как определить, для кого вы пишете?

Не нужно проводить масштабное UX-исследование. Достаточно задать себе несколько вопросов перед началом работы:

1. Этот материал будет читать новичок или опытный пользователь?
2. Читатель пришел разобраться в теме или быстро решить конкретную проблему?
3. Документ будут читать индивидуально или обсуждать в команде?
4. Сколько времени готов потратить читатель — 3 минуты или 3 часа?

Ответы на эти вопросы напрямую влияют на:
- Структуру и объем текста
- Выбор терминологии
- Глубину объяснений
- Формат подачи материала (статья vs справка)


Практический пример: оптимизация индексов в базе данных

🐣 Для новичка
«Индексы в базе данных — это как оглавление в книге. Они помогают быстрее найти нужную информацию, не просматривая все страницы подряд. Когда вы часто ищете определенные данные (например, товары по категории), индекс ускоряет этот поиск в десятки раз. Давайте рассмотрим пошагово, как создать свой первый индекс...»

🪿 Для опытного разработчика
«Составной индекс по полям (client_id, created_at) ускорит выборку в запросах с условиями по обоим полям, но увеличит нагрузку при вставке новых записей. Перед добавлением оцените баланс между частотой чтения и записи в таблицу. Для таблиц с высокой нагрузкой на запись рассмотрите возможность асинхронного создания индексов.»

🕷 Для интегратора
«При проектировании схемы взаимодействия учитывайте, что запросы к индексированным полям из внешних систем могут использовать кэширование на уровне БД. Убедитесь, что ваш API корректно передает параметры сортировки, соответствующие структуре индексов, особенно для составных индексов.»

🐝 Для техподдержки
«Если клиент сообщает о замедлении запросов после обновления, проверьте состояние индексов через SHOW INDEX FROM table_name. Фрагментация выше 30% может требовать перестроения индекса. Для временного решения без перестроения можно использовать FORCE INDEX в критичных запросах.»

Каждый раз, когда садитесь писать технический текст, спросите себя: кому я сейчас это объясняю?

Если не знаете — узнайте ауф. Если нельзя узнать — выберите одну приоритетную аудиторию и пишите для неё. Лучше создать несколько целевых документов для разных аудиторий, чем один универсальный, который не подойдет никому.

Американский центр производительности и качества APQC опубликовал ежегодный отчёт о состоянии управления знаниями на 2025 год. В исследовании приняли участие сотни экспертов и практиков Knowledge Management, что позволило зафиксировать текущее положение дел и обозначить ключевые тенденции.

Спасибо Лане, что напомнила о его существовании, я в этом году немного слоу 🦥

Отчёт опубликовали ещё в январе, но в целом информация не то чтобы успела устареть — состояние ноуледж менеджмента в некоторых российских компаниях отстаёт от трендов на несколько лет минимум 😔

➡️ Итоги и тренды отчёта APQC 2025 по управлению знаниями ⬅️

📈 1. Приоритеты KM: смена фокуса

2024: Главный приоритет — идентификация и приоритизация критически важных знаний.
2025: На первое место вышло внедрение ИИ и «умных» технологий в KM.

🤖 2. Технологические тренды: от экспериментов к внедрению

2024: ИИ рассматривается как перспективное направление, но находится на стадии экспериментов.
2025: Генеративный ИИ и интеллектуальные рекомендации стали ключевыми технологиями в KM.

🧠 3. Передача экспертных знаний

2024: Передача экспертных знаний — один из основных приоритетов.
2025: Остаётся важной задачей, но уступает место технологическим инициативам.

🧩 4. Культурные барьеры: устойчивые препятствия
моё любимое

2024: Основные барьеры — нехватка времени у сотрудников и отсутствие поддержки руководства.
2025: Те же проблемы сохраняются, дополняясь усталостью от изменений.

📊 5. Инвестиции в KM: рост уверенности

2024: Инвестиции в KM остаются стабильными.
2025: Ожидается увеличение инвестиций, особенно в технологии.

🛠 6. Навыки KM-команд: изменение акцентов

2024: Наиболее востребованный навык — управление изменениями.
2025: Важность управления изменениями сохраняется, но растёт потребность в навыках работы с ИИ и дизайном пользовательского опыта.

В понедельник буду на Knowledge Conf в Москве — пишите, если вы тоже 🐤

Новая конфа! 🆕

Вместе с командой Стачки делаем отдельную конференцию только про тексты — WriteConf

25 августа, Москва

Пока планируем два потока: по внешним и внутренним текстам, но окончательно будем отталкиваться от ваших заявок и запросов аудитории.

▶️ Внешние: от маркетинга до пользовательских инструкций. Можно подавать доклады про тексты в интерфейсе, работу на разные аудитории, b2b-коммуникации и всё, что считаете важным сказать.

▶️ Внутренние: от доки для разработчиков до управления знаниями в компаниях. Всё, что касается коммуникаций внутри компании и команд — тоже не ограничивайте себя в подаче заявки, будем решать по ходу.

🔥 Подать заявку 🔥

🌞 Ещё про конфы

19 сентября в Екатеринбурге проводим конференцию для руководителей

Уже говорила про неё, но буду ещё много рассказывать 😁

Открыт приём заявок

Ждём темы по управлению командами в любой трактовке. В фокусе конференции — отношение к сотрудникам как к людям, а не просто к функции.

Специальный корреспондент Екатерина сегодня для вас на Knowledge Conf генерит контент 🔥🔥

💡 Шаблон, который живёт сам

Когда в команду падает сто-первый тикет «нужен такой же документ, как у ребят из соседнего отдела. вчера.», руки сами тянутся к Ctrl +C / Ctrl +V. А потом мы сидим ночью и переписываем шапку, потому что там всё ещё имя Пети-фронтендера, который уволился 7 лет назад, но всё ещё упоминается в каждом скопированном доке.

Знакомая ситуация? Не редко значительная часть времени на создание документации тратится именно на поиск «того самого шаблона» и его адаптацию под текущую задачу. При этом команды постоянно используют одни и те же базовые форматы документов.

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


1️⃣ Привязываем шаблон к событию, а не к человеку

• Jira Automation Rules: тип задачи → автосоздание по шаблону
• GitHub Actions: новый PR с лейблом needs-docs → создание issue с шаблоном документации
• Confluence Blueprint: кастомный шаблон для каждого типа проекта

Конкретный пример: Новая фича в Jira? В момент перехода в статус *Ready for Docs* автоматически создаём черновик ТЗ с уже заполненными разделами:
- Цель (подтягивается из Description задачи)
- Метрики (предзаполнены стандартные KPI)
- Команда (автоматически из Assignee и Watchers)
- Дедлайн (берётся из Due Date + 3 дня на документацию)

Результат: Заявка приходит к техпису заполненной на 80% — меньше шансов, что кто-то «забудет» про бизнес-часть или строку про откат.

> Метрика успеха: Время от постановки задачи до готового драфта сократилось с 2-3 дней до 4-6 часов.


2️⃣ Добавляем умные подсказки внутрь шаблона

Не просто placeholder, а реальная помощь:

❌ Плохо: "--- опишите риски ---"
✅ Хорошо: "Риски (обязательно указать технические, бизнес и UX-риски):
• Технические: падение производительности, совместимость с браузерами
• Бизнес: влияние на конверсию, время внедрения
• UX: изменение привычного пользовательского пути"

Продвинутые фишки:
• Условная логика: если выбран тип "Breaking Change" → показываем дополнительные поля про миграцию
• Валидация: пустые критические поля подсвечиваются красным
• Авто-пинги: бот напоминает через 24 часа, если остались незаполненные обязательные разделы

Инструменты: Notion Database с формулами, Google Forms с условной логикой, кастомные Confluence macros.


3️⃣ Делаем шаблон частью процесса, а не PDF-файлом

Интеграция с кодовой базой:
• Храним в репозитории в папке .github/ISSUE_TEMPLATE/ или docs/templates/
• Версионируем через Git: каждое изменение = отдельный commit
• Code review для изменений шаблонов как для обычного кода

Результат: Изменилось поле в базе? MR с миграцией автоматически подтягивает обновление в шаблоне Release Notes — без ручной правки.


4️⃣ Проверяем «дыхание» данными, а не интуицией

Ежемесячная аналитика использования:
• Confluence Analytics: какие разделы шаблона заполняются чаще всего
• Jira Query: сколько задач созданных по шаблону закрываются без доработок
• Опрос команды через Slack polls каждый квартал

Чек-лист ревизии шаблона:
- [ ] Все поля заполняются >80% случаев? (Если нет — убираем или делаем опциональными)
- [ ] Время заполнения <15 минут для опытного сотрудника?
- [ ] Новичок может разобраться без объяснений за 30 минут?
- [ ] Есть ли поля-дубли с другими инструментами? (RACI в шаблоне + RACI в Confluence)

Правило 3 кликов: Если команда в опросе ставит «лишних действий > » для достижения цели — упрощаем или автоматизируем.

Продолжение

❗️ Осторожно: побочные эффекты

Проблема 1
Команда перестанет думать и будет просто заполнять поля

Решение
1. Раздел «Пример» рядом с каждым «Описание» — показываем зачем поле нужно.
2. Обязательная peer-review критических разделов (метрики, риски, compliance).
3. «Резиновые» поля: оставляем возможность добавить нестандартный раздел


Проблема 2
Шаблон становится слишком универсальным и бесполезным

Решение
Делаем 3-4 специализированных шаблона вместо одного на все случаи жизни:
• Техническое ТЗ — для backend/API
• Product Requirements — для фич
• Release Notes — для деплоев
• Post-mortem — для инцидентов


⭐️ Метрики успеха живого шаблона

• Time to first draft: от задачи до первой версии документа
• Revision cycles: сколько итераций до финальной версии
• Template adoption rate: % задач, где использовался шаблон vs создано с нуля
• Satisfaction score: оценка удобства от команды (NPS)


🎧 Конкретные инструменты для старта

Для небольших команд <20 человек:
• Notion с Database и Templates
• Google Docs с готовыми шаблонами в общей папке
• Slack Workflow Builder для простых форм

Для средних команд — 20-100 человек:
• Confluence с Custom Blueprints
• Jira Automation + ScriptRunner
• GitHub/GitLab Issue Templates

Для больших команд — 100+ человек:
• Confluence + Advanced Roadmaps
• ServiceNow или аналогичная ITSM система
• Custom разработка интеграций



⚪️⚪️⚪️
TL;DR

Живой шаблон — это:
1. Авто-создание по событию в тасктрекере
2. Умные подсказки вместо пустых полей
3. Версионирование в Git и релиз вместе с кодом
4. Data-driven ревизия каждый месяц + право переписать
5. Измеримые метрики вместо «кажется, стало лучше»


Домашнее задание: Выберите один самый используемый шаблон в команде и проведите мини-аудит: сколько времени тратится на его заполнение и какие поля остаются пустыми чаще всего.

Расскажите в комментариях, какой ваш самый полезный (или самый бесполезный 🩷) шаблон и какие метрики вы используете для оценки его эффективности.

⭐️ Метрики документации без фанатизма

12 мая мы убедили «техно-скептиков», что доки приносят бизнесу пользу. Следующий логичный вопрос: «А сколько приносит? Покажи цифры».

Большинство команд либо вообще не измеряют эффективность документации, либо тонут в дашбордах с 20+ метриками. Я покажу ровно пять показателей — не больше. Всё лишнее идёт в корзину, чтобы не раздувать отчётность и не сводить команду с ума.


1. Ratio «Просмотры статьи / тикеты в поддержку»

Логика: Если читатель нашёл ответ в документации — он не идёт к оператору поддержки. Поэтому относительное число тикетов важнее абсолютного.

Коэффициент самообслуживания = 
Просмотры статьи за период / Тикеты по той же теме за период

• Google Analytics/Yandex Metrica — для просмотров документации
• Zendesk/Intercom — экспорт тикетов с тегами по темам
• Confluence Analytics — встроенная статистика просмотров
• Custom dashboard — связываем через API или Zapier

Пример:
- Статья «Настройка API-ключей»: 450 просмотров в месяц
- Тикеты с тегом «api-setup»: 15 обращений
- Коэффициент: 450/15 = 30 — хороший показатель

Красные флаги:
- Тикеты растут ×7, а просмотры всего ×1,1 → статья устарела или её не находят
- Коэффициент <5 → либо документация неполная, либо плохо организована навигация
- Резкое падение просмотров при росте тикетов → возможно, статья "потерялась" после редизайна


2. Time-to-Answer (TTA)

Что измеряем: Сколько минут (или кликов) проходит от входа на портал документации до того момента, когда пользователь находит ответ и закрывает вкладку.

• Heatmap-сервисы (Hotjar, Yandex Webvisor) — видим реальное поведение
• Короткий поп-ап "Нашли, что искали?" при попытке закрыть вкладку
• Session recording — для deep-dive анализа сложных кейсов
• A/B тесты навигации — оптимизируем структуру под TTA

Бенчмарки:
- <2 минуты — отлично (пользователь быстро нашёл ответ)
- 2-5 минут — нормально (изучил несколько разделов)
- 5-10 минут — тревожно (либо сложная задача, либо плохая навигация)
- >10 минут — критично (нужен редизайн информационной архитектуры)


3. Coverage Ratio

(Функции с актуальной документацией / Все продуктовые функции) × 100%

Как определить актуальность:
• документация обновлена не позднее чем через N дней после релиза функции;
• нет противоречий с текущим UI/API;
• есть рабочие примеры кода или скриншоты.


• Swagger/OpenAPI + автогенерация документации
• Confluence labels для маркировки актуальности
• Jira integration — автоматическое создание задач на документирование новых фич
• Git hooks — проверка наличия документации при мерже фичи

Целевые показатели:
- >90% — зрелые продукты с устойчивыми процессами
- 70-90% — растущие продукты, нормальный уровень
- <70% — нужно срочно наверстывать документацию


4. NPS/CSI по документации

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

Ultra-лайт версия:
Всплывающее окно раз в квартал с одним вопросом: «Насколько документация помогла вам сегодня? От 0 до 10»

Расширенная версия:

1. Насколько вероятно, что вы порекомендуете нашу документацию коллеге? (0-10)
2. Что было самым полезным сегодня?
3. Чего не хватило для решения задачи?
4. Ваша роль: [Developer/QA/Support/PM/Other]

• Typeform/Google Forms — простой старт
• Hotjar Surveys — контекстные опросы на страницах
• Custom solution — интеграция с системой аналитики
• Slack/Teams боты — опросы прямо в рабочих каналах

Интерпретация результатов:
- NPS >50 — пользователи реально довольны документацией
- NPS 0-50 — есть проблемы, но не критично
- NPS <0 — срочно нужны изменения

Сегментация ответов:
Разделяйте по ролям — требования разработчика и саппорта к документации кардинально разные.

5. Update Lag

Что измеряем: Разница между мержем кода и обновлением соответствующей документации.

• GitHub/GitLab webhooks — автоматические уведомления о необходимости обновить документацию
• Jira automation — создание подзадач на документирование при мерже фичи
• Slack боты — ежедневные напоминания о просроченной документации
• Definition of Done — документация как обязательная часть готовности фичи

Целевые значения:
- 0-2 дня — зелёная зона (идеальный процесс)
- 3-7 дней — жёлтая зона (повод разобраться с процессами)
- 7+ дней — красная зона (высок риск, что пользователи уже столкнулись с проблемами)

Исключения из правил:
• Hotfix — документация может подождать 1-2 дня
• Internal tools — менее критично, можно до недели
• Breaking changes — документация должна быть готова до релиза



🍨 Как не превратить метрики в цель

Любую цифру можно «взломать». Классика жанра: обещали премию за количество статей — получили тонны дублей и копипасты без пользы.

Антипаттерны и защита от них

Проблема: Гонка за количеством просмотров
Решение: Смотрим на конверсию в полезное действие, а не только на трафик

Проблема: Искусственное завышение NPS
Решение: Анонимные опросы + рандомная выборка респондентов

Проблема: «Галочная» документация для улучшения Coverage
Решение: Добавляем метрику качества — например, процент документации с рабочими примерами

Основные принципы:
1. Смотрим в связке — один показатель скачет? Проверяем остальные.
2. Приоритизируем «пользовые» над «объёмными» — просмотры/тикеты важнее количества страниц.
3. Делаем ретроспективы — раз в квартал сверяем гипотезы с реальностью.
4. Фокусируемся на тренде, а не на абсолютных значениях.



↗️ Дашборд мечты: как всё свести вместе

📈 Текущая неделя vs прошлая:
• Просмотры/Тикеты: 15.2 (+2.1)  
• Средний TTA: 3.4 мин (-0.8 мин)
• Coverage: 87% (+3%)
• Update Lag: 2.1 дня (+0.3 дня)

🔴 Требуют внимания:
• API документация: coverage 45% 
• Статья "Биллинг": TTA 8.2 мин

• Grafana — если есть техническая команда
• Google Data Studio — быстрый старт с готовыми коннекторами
• Notion — простые таблицы с формулами
• Confluence Analytics — встроенные отчёты


✏️ План внедрения метрик за 4 недели

Неделя 1: Настраиваем сбор данных
- Подключаем аналитику к документации
- Настраиваем теги в системе поддержки
- Создаём простую форму для NPS

Неделя 2: Собираем базовые данные
- Получаем исторические данные за последний месяц
- Определяем текущие значения всех 5 метрик
- Выявляем главные проблемы

Неделя 3: Устанавливаем цели и процессы
- Договариваемся о целевых значениях с командой
- Внедряем процесс еженедельного мониторинга
- Настраиваем автоматические алерты

Неделя 4: Первые улучшения
- Исправляем самые критичные проблемы
- Запускаем A/B тест одного изменения
- Планируем долгосрочную стратегию развития


⬇️ А теперь интерактив