⚡️ Гайд по объяснению пользы документации
или что сказать, когда спросят «зачем вообще это писать?»

Иногда кажется, что ты и так всё рассказал. И даже дважды.
Но потом кто-то говорит:
— Ну мы ж и так понимаем, зачем писать документацию…
— …чтобы была.
🫠🫠🫠

Вот короткий гайд, что можно отвечать:

📍 «Документация снижает количество повторных вопросов»
Если к тебе три раза подряд приходят с одинаковым вопросом — текст на эту тему может сэкономить всем время. Особенно твоё.

⏳ «Она сохраняет знания команды»
Даже если ты ушёл в отпуск, заболел, сменил проект — твои ответы остались. И не надо устраивать археологию по чатам.

🗝 «Помогает онбордить новых сотрудников»
Хорошо написанный гайд быстрее отвечает на вопрос «с чего начать?», чем любые welcome-созвоны.

☯️ «Поддерживает процессы»
Если договориться, что всё проходит по инструкции, не надо каждый раз решать «а как на этот раз?».

🎱 «Дает точку отсчёта для анализа»
Что мы обещали клиенту? Где фиксировали процесс? Чем текущее поведение отличается от запланированного?


И, конечно:

💎 документация не просто хранит информацию, а помогает передавать её

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

#этобаза

👇 Психология восприятия технических текстов
документация создаётся для читателя, а не для автора

Одна из основных ошибок при создании документации — проецирование собственного знания на читателя. Этот феномен описывается в психологии как проклятие знания (curse of knowledge) — когнитивное искажение, при котором человеку трудно представить, каково это — не знать того, что ему известно.

Авторы документации, обладая глубоким контекстом о системе, часто случайно опускают важные связки, вводные понятия и промежуточные выводы. В результате текст получается неполным и трудным для восприятия теми, кто не настолько в контексте [всеми].

Простой способ убедиться в существовании этого «проклятия» — перечитать собственную документацию спустя пару-тройку месяцев. Большинство авторов замечают, что отдельные детали забылись, а логика изложения требует усилий для восстановления.
❗️Именно в таком положении находится читатель с самого начала.

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

0⃣ Когнитивная нагрузка: три компонента

Теория когнитивной нагрузки (Sweller, 1988) выделяет три основных типа ментальной нагрузки, возникающей при обучении или восприятии новой информации:

🟡Внутренняя (intrinsic load) — определяется природной сложностью самого материала.
🟡Внешняя (extraneous load) — обусловлена способом подачи информации: структурой, форматом, визуальными шумами.
🟡Продуктивная или связанная (germane load) — усилия, направленные на построение устойчивых когнитивных схем и интеграцию нового знания.

Если суммарная нагрузка превышает возможности рабочей памяти (Miller, 1956; Baddeley & Hitch, 1974), восприятие текста нарушается: читатель испытывает трудности в удержании смысловых блоков и теряет нить повествования.

1️⃣ Как проектировать документацию с учётом когнитивных ограничений

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

1. Чанкинг: группировка информации в компактные логические блоки (3–5 элементов). Это снижает нагрузку на рабочую память и помогает лучше запомнить информацию (G. A. Miller, 1956).

2. Визуальная иерархия: оформление текста заголовками, списками, таблицами и врезками помогает читателю ориентироваться в структуре документа и быстрее находить информацию.

3. Примеры и сценарии использования: конкретизация абстрактных концепций упрощает их понимание и повышает прикладную ценность текста.

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

2️⃣ Как оценить понятность документации

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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


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

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

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

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


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

- Первый абзац отвечает на вопрос что это и зачем?
- Можно ли понять основную идею за 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. Измеримые метрики вместо «кажется, стало лучше»


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

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