Как писать статьи для центра помощи, которыми действительно пользуются
Кто-то вводит в поиск вашего центра помощи «выгрузить счета». В выдаче три результата: «Обзор оплаты», «Отчёты» и «Начало работы с данными». Ни в одном нет слова «выгрузка». Человек закрывает вкладку и пишет вам на почту.
В этом проблема большинства статей центра помощи. Они устроены по логике того, как построен продукт, а не по тому, что люди пытаются сделать.
Вот короткий ответ. Чтобы писать статьи для центра помощи, которыми действительно пользуются, назовите каждую по одной задаче словами клиента, одной строкой скажите, что она делает, перечислите всё, что нужно сделать заранее, дайте пронумерованные шаги по одному действию в каждом, добавьте скриншот там, где люди обычно теряются, и закончите тем, что они должны увидеть, когда всё получилось. Одна статья, одна задача. Если вы ловите себя на словах «также можно», вероятно, это уже вторая статья.
Остальная часть материала — подробности: шаблон, который можно скопировать, пример переписывания «до и после», с чего начинать и как не дать всему устареть через шесть недель после запуска.
Что делает статью базы знаний хорошей?
Никто не читает справку ради удовольствия. Люди приходят в середине задачи, слегка раздражённые, обычно из поиска (вашего или Google) или по ссылке, которую кто-то из вашей команды вставил в ответ. Они просматривают текст по диагонали. Им нужно найти шаг 3, выполнить его и уйти.
Поэтому хорошая статья базы знаний позволяет просматривающему по диагонали, слегка раздражённому человеку выполнить задачу, ничего не перечитывая дважды. На практике это значит:
- Одна статья, одна задача. «Пригласить коллегу» и «Изменить роль коллеги» — две разные статьи. Они ссылаются друг на друга.
- Заголовки похожи на поисковые запросы. Люди ищут глаголами: «отменить подписку», «сбросить пароль», «подключить Slack». Ваши заголовки должны звучать так же.
- Шаги пронумерованы и неделимы. Один клик или одно поле на шаг. Если в шаге есть «а затем», разделите его.
- Точные названия элементов интерфейса, жирным шрифтом. Если на кнопке написано Добавить участника, не пишите «нажмите кнопку приглашения». Читатель сопоставляет слова на экране со словами в вашей статье.
- В конце результат. «Они появятся в списке участников с отметкой «Ожидает», пока не примут приглашение». Эта строка говорит людям, что они закончили, и именно её большинство авторов пропускает.
Фреймворк Diátaxis делит документацию на обучающие материалы, практические руководства, справочники и объяснения. Большинство статей центра помощи должны быть практическими руководствами. Распространённая ошибка — смешивать все четыре типа на одной странице, из-за чего человеку, которому нужен шаг 4, приходится пробираться через три абзаца о том, зачем существует функция.
Шаблон статьи центра помощи, который можно скопировать
С этого шаблона я бы начинал каждую статью-задачу. Он подходит для Zendesk, Intercom, Help Scout, GitBook или папки с файлами Markdown в вашем репозитории.
# [Verb] [the thing]
<!-- e.g. "Export your invoices to CSV" -->
[One or two sentences: what this does and when you'd want it.
Mention the plan or role if it's restricted.]
**Before you start**
- You need [role or permission], e.g. Admin or Owner
- [Anything to have ready: a file, an API key, a connected account]
## Steps
1. Go to **[Page name]** in the left sidebar.
2. Click **[Exact button label]**.
3. In **[Field name]**, enter [what, with an example value].
4. Click **[Confirm button label]**.
<!-- Screenshot of the step where people get stuck.
Crop to the relevant area, highlight the target. -->
## What happens next
[What they'll see when it worked. How long it takes.
Who gets notified.]
## If it didn't work
- **[Symptom in the customer's words]**: [cause and fix]
- **[Second most common symptom]**: [cause and fix]
## Related
- [The task people usually do next]
- [The reverse task, e.g. "Remove a teammate"]
Несколько замечаний по использованию.
Вступление — не рекламный текст. «Наша мощная функция экспорта даёт вам полный контроль над данными» ничего не сообщает читателю. «Скачайте все счета за выбранный период в виде CSV-файла, который можно открыть в Excel или Google Таблицах» подскажет, на той ли он странице.
Блок «Прежде чем начать» предотвращает больше всего обращений. Классический провал: человек выполняет шесть шагов, а на седьмом выясняет, что это могут делать только администраторы. Указывайте права и ограничения тарифа в начале, а не в примечании внизу.
Раздел «Если не получилось» должен опираться на реальные обращения. Не придумывайте устранение неполадок. Просмотрите переписку с поддержкой за последний месяц и запишите, на чём люди действительно застревали. Двух-трёх пунктов вполне достаточно. Если нужен повторяемый способ, у нас есть отдельное руководство о том, как превращать обращения в поддержку в статьи справки.
«До» и «после»: переписываем типичную статью справки
Вот статья, какие пишут на той неделе, когда выходит функция. Продукт вымышленный, но схема реальная.
Управление командой
Наша функция управления командой упрощает совместную работу. В разделе настроек вы можете управлять своей командой, в том числе добавлять новых участников на вкладке «Участники», где находится кнопка «Добавить участника», и выбирать роли, такие как «Администратор», «Редактор» или «Наблюдатель», которые определяют, к чему имеет доступ каждый человек. Приглашённые пользователи получат письмо. Обратите внимание, что добавлять участников могут только администраторы, а количество мест зависит от вашего тарифа.
Всё, что нужно читателю, там есть. Но в неправильном порядке, под заголовком, который никто не ищет, а оговорка о правах стоит в последнем предложении.
Вот переписанный вариант:
Пригласить коллегу
Добавьте человека в рабочее пространство, чтобы он мог просматривать и редактировать проекты.
Прежде чем начать: вы должны быть администратором. Каждый человек занимает одно место на вашем тарифе. Сколько мест осталось, можно посмотреть в разделе Настройки > Оплата.
- Откройте Настройки > Участники.
- Нажмите Добавить участника.
- Введите его адрес электронной почты.
- Выберите роль: Администратор, Редактор или Наблюдатель.
- Нажмите Отправить приглашение.
Что будет дальше: человек получит приглашение по почте. Пока он его не примет, в списке участников у него будет отметка Ожидает.
Если не получилось: если кнопка Добавить участника неактивна, все места заняты. Удалите кого-нибудь или добавьте места в разделе Настройки > Оплата.
Те же факты, примерно та же длина. Но заголовок совпадает с тем, что вводят люди, оговорка стоит в начале, каждый шаг — одно действие, и читатель знает, когда он закончил. Объяснения ролей перенесены в отдельную короткую статью («Что может каждая роль») со ссылкой из шага 4.
Какой длины должна быть статья центра помощи?
Столько, сколько нужно для задачи, и не больше. Как правило, практическое руководство по одной задаче занимает от 150 до 500 слов. Если вы заметно превысили этот объём, проверьте, не склеили ли вы две задачи и не ушли ли в объяснение философии функции.
Исключение — руководства по настройке, например «Подключите магазин Shopify», где действительно десяток шагов в двух системах. Они могут быть длинными, если разбить их на разделы H2, к которым можно перейти.
Где скриншоты помогают, а где вредят
Скриншоты читатели замечают больше всего, а команды поддерживают хуже всего.
Используйте их там, где интерфейс неоднозначен: перегруженная страница настроек, модальное окно с шестью полями, кнопка не там, где её ждут. Для «нажмите «Сохранить»» они не нужны. Обрезайте плотно по важной области и подсвечивайте цель, если экран загружен.
Загвоздка в том, что каждый скриншот — обещание, что интерфейс всё ещё так выглядит. Переместите меню, и десятки статей молча показывают клиентам экран, которого больше нет. Это главный довод в пользу автоматизации вместо ручных снимков. Мы сравнили варианты (скрипты Playwright, программы записи экрана, инструменты, которые делают снимки за вас) в материале как автоматически создавать скриншоты продукта.

С чего начать писать
Если вы начинаете с нуля, не пытайтесь описать каждую функцию. Пишите в таком порядке:
- Первые пятнадцать минут. Регистрация, первый шаг настройки, первый момент «о, это полезно». Эти статьи читает каждый новый пользователь.
- Главные вопросы в поддержку. Просмотрите свою почту. На всё, на что вы отвечали три раза за месяц, нужна статья.
- Всё, что связано с деньгами или данными. Изменения оплаты, отмена, удаление, экспорт. Здесь люди нервничают и хотят определённости, а не расплывчатого абзаца.
- Интеграции. Подключение сторонних аккаунтов — место, где люди застревают на экранах, которые вы не контролируете.
- Всё остальное, примерно в порядке того, как часто люди с этим сталкиваются.
Сгруппируйте статьи в несколько коллекций с названиями так, как думают клиенты: «Начало работы», «Оплата и аккаунт», «Работа с [вашей основной функцией]», «Интеграции», «Устранение неполадок». Избегайте коллекций, которые повторяют структуру ваших внутренних команд.

Как писать справку: мелкие привычки, которые складываются в результат
- Пишите во втором лице и в настоящем времени: «Нажмите», «Вы увидите».
- Используйте реальные названия из продукта, даже если считаете их неудачными. А потом идите и исправляйте название.
- Делайте абзацы из двух-трёх предложений.
- Используйте выноски экономно. Примечание для чего-то полезного, предупреждение для необратимого. Если в каждой статье по три предупреждения, люди перестают их замечать.
- Показывайте, когда статья обновлялась в последний раз, чтобы читатели (и вы) понимали, насколько она свежая.
- Ссылайтесь вперёд. Каждая статья должна указывать на то, что люди обычно делают дальше.
Руководство по стилю документации для разработчиков от Google рассчитано на техническую документацию, но большинство его советов о ясности и тоне подходят и для справки для клиентов.
То, что никто не планирует: поддержание точности статей
Написать статью — это легкая часть. Трудность в том, что продукт меняется каждую неделю, а центр помощи нет.
Каким бы инструментом вы ни пользовались, помогает следующее:
- Помечайте каждую статью функцией или экраном, о которых она, чтобы при изменении функции вы точно знали, какие статьи проверять.
- Сделайте «документация проверена» частью определения готовности для любого PR, который меняет тексты интерфейса или пользовательский сценарий.
- Перечитывайте самые посещаемые статьи примерно раз в месяц. Именно там устаревший скриншот причиняет больше всего вреда.
- Следите за поисковыми запросами без результатов. Это бесплатный список статей, которые вы ещё не написали.
Мы подробно разбираем это в статье как поддерживать документацию в актуальном состоянии, включая то, как привязать проверку документации к процессу выпуска. А если вы публикуете заметки о выпусках, та же дисциплина действует и там: см. как писать список изменений, который клиенты действительно читают.
Где подходит Ellie Docs
Раскрою интерес: мы делаем инструмент для этого. Ellie Docs подключается к вашему репозиторию GitHub, читает код, чтобы определить ваши функции и экраны, видимые пользователям, и составляет черновик полного центра помощи. Она запускает ваше приложение в песочнице, снимает реальные скриншоты продукта под учётной записью пользователя и размещает их в статьях.

Больше всего меня волнует поддержка актуальности. Когда PR сливается, Ellie проверяет, какие статьи затрагивает изменение, и предлагает правки в виде диффа, который вы принимаете или отклоняете. Ничего не публикуется само. Вы по-прежнему решаете, что читают клиенты, просто перестаёте узнавать из обращения в поддержку, что шаг 6 уже месяц неверен.
Если у вас уже есть центр помощи, она импортирует существующие статьи как черновики, так что начинать с нуля не придётся. Есть бесплатный тариф, карта не нужна.
А если вы предпочитаете всё делать вручную, шаблон выше отлично работает и сам по себе.
Несколько вопросов, которые задают чаще всего
Чем центр помощи отличается от базы знаний? На практике почти ничем. «База знаний» обычно означает набор статей, а «центр помощи» — сайт для клиентов с поиском и навигацией поверх него. В большинстве инструментов эти термины используются как взаимозаменяемые.
Кто должен писать статьи справки: поддержка, продукт или разработка? Тот, кто ближе всего к вопросам. Поддержка знает, что сбивает людей с толку, разработка знает, что изменилось. Хорошо работает схема, когда центр помощи ведёт поддержка, а инженеры отмечают затронутые статьи в своих PR.
Хотите получить первый черновик своего центра помощи, написанный по вашей кодовой базе? Попробуйте Ellie Docs бесплатно и посмотрите, что получится из вашего репозитория.