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


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

☕️ Пакуем доки под аудиторию: быстрый рецепт на 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 — об этом маленькое вертикальное видео.

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

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

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

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

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

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