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

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 тест одного изменения
- Планируем долгосрочную стратегию развития


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

☕️ Пакуем доки под аудиторию: быстрый рецепт на 15 минут

Целевая аудитория — это люди, у которых возникла проблема, и мы решаем эту их проблему нашим документом. Поэтому один и тот же текст никогда не подойдёт всем сразу.

Когда мы делаем универсальную документацию, она не подходит никому. Джуниор тонет в технических деталях, а сеньор закрывает страницу из-за воды. Это мы уже обсуждали недавно 🙂

Вот алгоритм, как за 15 минут упаковать документ под конкретную аудиторию.


0⃣ Ключевые вопросы
~ 5 мин

Честно отвечаем на три ключевых вопроса:

Кто читатель?
Роль + уровень экспертизы + контекст работы
• Dev Junior (0-2 года)
• Product Manager (знает бизнес, не знает техники)
• CFO (нужны только цифры и риски)

Что у него уже есть?
Инструменты, знания, доступы
• «Знает Swagger, но не умеет читать логи»
• «Есть админка, нет доступа к базе»

Чего он боится?
Основные риски и болевые точки
• «Сломать продакшн одним коммитом»
• «Потерять пользовательские данные»
• «Не уложиться в дедлайн»


1️⃣ Аудит-микс
~ 4 мин

Определяем четыре параметра упаковки:

Формат
• Статья/гайд — для изучения концепций
• Туториал step-by-step — для конкретной задачи
• Чек-лист — для проверки готовности
• One-pager — для быстрых решений

Глубина
• Full deep-dive — все детали и edge cases
• Core concepts — основы + 2-3 примера
• TL;DR — только ключевые действия

Стиль
• Dry & formal — факты без эмоций
• Friendly — как объясняешь коллеге за кофе
• Problem-solution — сначала боль, потом решение

Канал
• Help-центр/Wiki — справочная информация
• README — для разработчиков
• Email/Slack — срочные обновления


2️⃣ Матчинг
~ 3 мин

Собираем прошлые шаги

Формула: Роль + Контекст + Страхи = Формат + Глубина + Стиль + Канал

Примеры
Dev Junior + «нет опыта с Git» + «боится сломать репозиторий»
= Пошаговый туториал + Core concepts + Friendly + README
= «Git для начинающих: безопасные команды с примерами отката»

CFO + «нужны только цифры» + «боится лишних трат»
= One-pager + TL;DR + Formal + Email
= PDF с ROI-калькулятором и таблицей рисков


3️⃣ Проверка
~ 3 мин

Отдаём черновик реальному представителю аудитории и задаём два вопроса:

1. «Что ты сделаешь после чтения?»
✔️ «Настрою webhook по инструкции»
✖️ «Разберусь с интеграцией»

2. «Где ты споткнулся?»
✔️ «Не понял, что такое payload в шаге 3»
✖️ «Всё понятно»


〰️〰️〰️
📌 Чек-лист готового документа

Структура
☐ Заголовок отражает конкретную пользу
☐ Есть TL;DR в начале
☐ Логические блоки до 3-4 предложений
☐ Примеры для каждого утверждения

Контент
☐ Убраны жаргонизмы
☐ Ссылки работают
☐ Есть способы проверить правильность
☐ Расписаны альтернативы для edge cases


📕 Шаблон для быстрого старта

Заголовок: [Действие] для [роль] за [время]

Структура:
1. TL;DR (результат в 2-3 предложения)
2. Что понадобится (prerequisites)
3. Пошаговая инструкция
4. Проверка результата
5. Troubleshooting
6. Дополнительные ресурсы

Ключевой принцип: лучше написать 3 коротких документа для разных ролей, чем один «универсальный» на 20 страниц.

Привет с Saint TLC 👐

собираю сегодня свои фотки по чужим каналам, самой нечего выкладывать 🤭

неистово нетворкаемся, пишите, если хотели пойматься завтра 🙌

Была в Питере на Saint Teamlead Conf — об этом маленькое вертикальное видео.

Но кроме мерча с конференции, налутала сборник китайских анекдотов 😅

Делюсь своими любимыми:

Три генерала стояли и спорили, чьи войска самые смелые.
Первый подзывает к себе двух солдат и говорит им: «Полезайте на тот флагшток и снимите с него флаг».
Солдаты лезут, снимают флаг, отдают его генералу.
Второй генерал подзывает к себе своих солдат и говорит им: «Надевайте полное обмундирование, полезайте на флагшток и вешайте флаг обратно».
Солдаты одеваются, лезут, возвращают флаг на место.
Третий генерал смотрит на всё это, подзывает пару своих солдат и говорит: «Полезайте на флагшток в полной экипировке и с оружием и станцуйте на его вершине».
Солдаты переглянулись и отвечают генералу: «Генерал, вы совсем с ума сошли?»
Третий генерал поворачивается к первым двум генералам и говорит: «Вот это — настоящая храбрость!»

Мама-крыса шагала по полу кухни вместе со своими крысятами. И вдруг выскочил кот и замяукал: «Мяу-мяу!».
Мама-крыса тоже замяукала в ответ: «Мяу-мяу!».
Глупый кот ушёл, а мама-крыса повернулась к своим крысятам и сказала: «Вот видите, я была права — выучить ещё один иностранный язык всегда пригодится».

Однажды красивая воробьиха обнаружила худую и немощную гусеницу. Гусеница сразу пролепетала: «Не ешь меня! Я покажу тебе, где дом моих приятелей. Они все жирнее и симпатичнее меня!».
А воробьиха отвечает: «Не стоит. Я на диете» и проглатывает гусеницу.

зацените какую сетку для вас собрали 🐈‍⬛️🐈‍⬛️🐈‍⬛️

В яхтинге есть два правила, которые я бы повесила над столом каждого менеджера
да и просто каждой команды

⛵️ 1. Сделай всё возможное, чтобы избежать столкновения — даже если придётся нарушить другие правила.
⛵️ 2. Всегда предоставляй достаточно пространства для манёвра.

И вот что это для меня значит, и не только на воде:

🚤 Первое правило — про ответственность
Ты можешь быть прав. Можешь идти по курсу. Можешь иметь приоритет.
Но если видишь, что будет авария — твоя обязанность сделать всё, чтобы она не произошла. Даже если придётся сдать назад, резко повернуть, нарушить ожидания других.

В работе это значит: «не моя зона ответственности» — не оправдание.
✨ Если горит — тушим, а не спорим, у кого был тикет.
✨ В конфликте — ищем решение, а не оправдание своей позиции.
✨ В коммуникации — пишем, зовём, уточняем, подсказываем. Даже если формально могли бы промолчать.


🚤 Второе правило — про уважение
Каждому участнику движения нужно пространство для манёвра.
Если ты всё делаешь идеально, но при этом не даёшь другим развернуться, адаптироваться, принять решение — ты не командный игрок. Ты — ледяная глыба на пути.

В работе это: не душить, не торопить, не подгонять на эмоциях.
✨ Оставлять время на обсуждение, обдумывание.
✨ Писать задачи так, чтобы человек мог в них вписаться.
✨ Заранее обозначать дедлайны и ожидания, чтобы было куда повернуть.


И ещё одно:

🛶 В столкновении всегда виноваты оба
Это не про поиск виноватого. Это про то, что мы всегда можем что-то сделать, чтобы не довести до столкновения.
И каждый из нас в ответе за общее движение.

Нам не нужно больше текстов
Нам нужно меньше тишины

Иногда кажется, что задача техписа — просто писать.
Добавить статью. Обновить инструкцию. Прописать шаги.
Кажется, что чем больше текстов, тем лучше станет понимание.

Но на деле часто оказывается, что дело не в количестве текста, а в том, что слишком многое остаётся несказанным

Что такое тишина в работе над продуктом?
Это не про спокойствие, а про молчание в местах, где что-то важно проговорить:

➡️ Где хранятся ключевые решения? — неясно.
➡️ Кто и зачем меняет поведение фичи? — нет общей картины.
➡️ Почему пользователь должен кликнуть сюда, а не туда? — приходится догадываться.

Интерфейс говорит одно, справка — ничего, а команда считает, что «и так понятно».

Технический писатель — не про текст, это про наведение ясности

Он убирает тишину между продуктом и пользователем.
Между командами, которые вроде бы договорились.
Между черновиком и релизом.
Между тем, что сделали, и тем, как это воспринимается.

Иногда, чтобы прояснить ситуацию, не нужно писать новый текст.
Достаточно задать вопрос. Или вовремя уточнить: «А как об этом узнают?»


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

И если кто-то открывает приложение и говорит: «Теперь всё ясно» — возможно, техпис просто помог задать нужный вопрос в нужное время 🪴

Документация — это налог на рост

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

✔️ Фичу можно объяснить голосом.
✔️ Новенького — посадить рядом и показать руками.
✔️ Решения — принять в чате и забыть через неделю.

Это работает. До тех пор, пока продукт и команда не начнут расти.
А потом внезапно всё становится дорого:

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

Документация — это налог на масштаб
Если хочешь расти — плати: временем, вниманием, усилием
Если не платишь — платишь другим: потерянными часами, недопониманием, ошибками, хаосом

Это не значит, что нужно завести 500 страниц и трекать каждую букву.
Это значит, что знание должно жить вне голов.
А процессы — быть хоть как-то оформленными.


✨ Чем больше команда, тем выше ставка.
✨ Чем сложнее продукт, тем меньше прощается.
✨ Чем быстрее ты хочешь двигаться — тем важнее, чтобы всё важное было зафиксировано.

Налог на рост всё равно придётся платить.
Вопрос в том — платишь ты его заранее, или каждый раз в аврале.

Какие-то излишне мотивационные посты в этом месяце получаются 😅

Добавлю ложку дёгтя

я вот пишу тут о том, какие классные на самом деле техписы и как они всем помогают идти в светлое будущее

но есть проблема
таких техписов не очень-то и много
скорее даже категорически недостаточно.

Что с этим делать — без понятия.
Для себя [своих команд и проектов] я решила, что проще брать людей с небольшим опытом и дальше обучать их быть теми самыми техписами.
Как решать вопрос глобально и надо ли вообще — не знаю 🙃

Вчера был спойлер от Милены
Сегодня — премьера пилотного выпуска

😉 Смотреть на YouTube
😄 Смотреть VK

Подкаст без названия и чёткого концепта, скорее эксперимент.
Вообще не уверена, что хочу использовать слово «подкаст» 🐈‍⬛️

Но тем не менее: в студии Маша Смирнова, руководитель технической редакции Ozon Tech. Говорили о везении на карьерном пути, роли опыта и визионерства — набрали 50 минут годного контента 🐈‍⬛️

Подписаться на Машу: @lostintechwriting

Не отменяйте встречи
хотя бы не отменяйте их молча

Снова #база, но у меня прям болит

✨ Допустим, это 1-1:
тут вообще не обсуждается — нельзя отменять 1-1, говорили об этом. Даже если 1-1 не руководитель-сотрудник, а между сиблингами и смежниками — это время, которое вы выделили друг на друга. У 1-1 может не быть шаблона или плана, самое ценное — вы выделили время строго на общение с одним конкретным человеком. Всё. Даже если вы поговорите о поливе цветов и самочувствии ящерицы — это важно и это нельзя отменять, тем более молча. Иначе это проявление неуважения и безразличия. А это путь в токсичность и разлад. Моё мнение по один-на-одинам однозначное: их. нельзя. отменять.

✨ Если это регулярная встреча больше, чем на двоих —
то тоже отменять единолично не стоит. Если вы организатор и у вас нет темы — она может быть у других участников. Они могли всё время от прошлой встречи копить темы и рассчитывать, что придут на регулярную встречу с регулярным составом, чтобы эти вопросы обсудить. Хочется отменить — уточните в чате, есть ли вопросы на встречу. Может быть вы не нужны для их обсуждения и можете пропустить одну конкретную встречу, а может быть кто-то из участников заметил важный риск и нёс его в расчёте на календарь. А вы просто молча решили встречу отменить.
Вот если несколько повторений подряд тем ни у кого нет — тогда стоит пересмотреть состав или регулярность. Тут тоже не надо засорять календарь себе и людям. Но тихо отменять — нельзя, табу.

✨ А если это разовая встреча по конкретному вопросу,
а вопрос взял и сам решился даже без встречи — всё равно важно уточнить у участников, что и для них тоже вопрос решился и встреча будет избыточна. Лучше созвониться и за 5 минут понять, что тема исчерпана, чем молча разойтись в недопонимании.


Да, переполненные календари — это проблема.
Но она не должна решаться тихой отменой встреч.