Как поддерживать документацию в актуальном состоянии, если вы выпускаете обновления каждую неделю
Клиент пишет: «В вашей инструкции сказано зайти в “Настройки”, затем в “Календарь”. Никакого “Календаря” нет». Он прав. Вы перенесли его в раздел «Аккаунты» шесть недель назад. PR проверили, протестировали и выпустили. Статья справки не изменилась, потому что менять её никто не был обязан.
Так возникает почти вся устаревшая документация. Дело не в лени, а в отсутствии связи между «мы изменили продукт» и «вот статьи, описывающие изменённую часть».
Чтобы поддерживать документацию в актуальном состоянии при еженедельных выпусках, сделайте документацию частью pull request: каждый PR отвечает на вопрос «меняет ли это то, что видит клиент?», называет затронутые статьи справки и несёт правку документации в том же PR или в связанном. Затем автоматизируйте механическую часть (скриншоты, записи списка изменений) и следите за обращениями в поддержку и поисковыми запросами в центре помощи, чтобы ловить расхождения, которые проскользнули.
Остальная часть материала — о том, как настроить это без найма технического писателя.
Почему документация устаревает
У расхождения документации есть несколько предсказуемых причин, и ни одну из них не устранить призывом «будем внимательнее».
Документация живёт в другом месте. Код в GitHub. Документация в Intercom, Zendesk, Notion или пространстве GitBook. Ничто не связывает файл в одном месте со страницей в другом, поэтому изменение в одном никогда не подталкивает заглянуть в другое.
Тот, кто знает, не тот, кто пишет. Инженер, переместивший настройки календаря, точно знает, что изменилось. Человек, который ведёт центр помощи, узнаёт об этом от клиента.
Документацию правят пакетами. «Займёмся документацией в конце квартала». А пока каждый еженедельный выпуск подтачивает точность, и большая переработка занимает так много времени, что к моменту выхода частично устаревает.
Никто не знает, какие статьи затронуты. Даже мотивированная команда не может проверить 80 статей после каждого выпуска. Поэтому не проверяет ни одной.
Схема та же, что и у любой другой работы по поддержке. Небольшие непрерывные обновления побеждают периодические героические усилия.
Сделайте документацию частью определения готовности
Самое эффективное изменение: добавьте раздел о документации в шаблон pull request. GitHub будет предзаполнять его в каждом PR, если положить файл .github/pull_request_template.md (руководство GitHub по шаблонам PR).
## Docs impact
- [ ] This changes something a customer can see or do
- Help articles affected: <!-- slugs or links, or "none" -->
- [ ] Screenshots need re-capturing
- [ ] Changelog entry drafted (or marked "internal only")
Примерно две недели это кажется бюрократией. А потом наступает момент, когда инженер говорит: «О, в статье по онбордингу упоминается этот экран», пока контекст ещё свеж. Правка документации в две строки, написанная тем, кто внёс изменение, лучше идеальной, написанной месяц спустя наугад.
Два правила, чтобы это закрепилось:
- Рецензенты ставят флажок. Если PR очевидно меняет интерфейс и говорит «влияния на документацию нет», рецензент спрашивает почему. Так же, как при отсутствии теста.
- Правка документации может быть черновой. Инженерам не нужно писать отполированную прозу. «Шаг 6 теперь: откройте “Аккаунты”, затем настройки доступности» достаточно. Формулировку кто-нибудь приведёт в порядок позже. Сначала точность.
Сопоставьте статьи справки с кодом, который они описывают
Чек-лист в PR рассчитан на то, что люди помнят, какие статьи существуют. Помогите им простой картой соответствия путей кода и статей:
# docs-map.yml
- paths: ["src/features/calendar/**", "src/pages/accounts/availability*"]
articles: ["connect-your-calendar", "set-your-availability"]
- paths: ["src/features/billing/**"]
articles: ["change-your-plan", "update-payment-method", "download-invoices"]
- paths: ["src/features/onboarding/**"]
articles: ["get-started"]
Затем небольшой шаг в CI читает список изменённых файлов (git diff --name-only origin/main...HEAD), сопоставляет их с шаблонами путей и оставляет в PR комментарий: «Этот PR затрагивает код календаря. Проверьте: connect-your-calendar, set-your-availability». Это примерно 40 строк скрипта, и он превращает «подумайте о документации» в конкретный список, по которому можно кликнуть.
Конечно, карта тоже устаревает. Храните её рядом с кодом и добавляйте строку, когда кто-то пишет новую статью. Всё равно её поддерживать гораздо проще, чем саму документацию.
Если документация лежит в том же репозитории (документация как код с чем-то вроде Docusaurus, Mintlify или Git Sync в GitBook), можно пойти дальше: запись CODEOWNERS для папки документации гарантирует, что каждое изменение проверит человек, которому небезразлична документация.
Пишите документацию, которая устаревает медленнее
Некоторые решения при написании сильно упрощают поддержку документации:
- Описывайте задачи, а не расположение. «Откройте Аккаунты и выберите Настройки доступности» переживёт редизайн. «Нажмите фиолетовую кнопку в правом верхнем углу» не переживёт.
- Используйте точные названия элементов интерфейса жирным шрифтом. Когда название меняется, поиск по старому названию находит все статьи, которые нужно исправить.
- Не повторяйте изменчивые факты. Лимиты тарифов, цены и длительность пробного периода меняются. Разместите их на одной странице и ссылайтесь на неё, а не повторяйте в десяти статьях.
- Снимайте стабильную часть. Обрезайте по элементу, о котором шаг, а не по всему экрану, чтобы изменение боковой панели не обесценивало каждое изображение.
- Показывайте дату «последнего обновления». Это держит вас в тонусе и говорит читателям, насколько можно доверять странице.
Подробнее о структуре в нашем руководстве по написанию статей для центра помощи, которыми действительно пользуются.
Автоматизируйте механическую часть
Часть поддержки документации требует суждения. Но многое — просто рутина, которую скрипт делает лучше.
Скриншоты. Переснимать изображения вручную — первое, что стоит автоматизировать. Скрипт на Playwright против демо-аккаунта с заготовленными данными, запущенный в CI, даёт свежие единообразные изображения при каждом слиянии. Полный скрипт мы разбираем в статье как автоматически создавать скриншоты продукта.
Записи списка изменений. Ваши слитые PR уже описывают, что вышло. Превратить их в список изменений для клиентов — это в основном переписать язык инженеров простыми словами и сгруппировать по Added, Changed и Fixed, как принято по соглашению, популяризированному Keep a Changelog. Шаблоны смотрите в материале как писать список изменений, который читают клиенты.
Видео. Если у вас есть обучающие видео, та же карта путей кода подскажет, какие нужно перезаписать. Раздельная запись изображения и голоса ускоряет переделку; вот процесс создания обучающих видео по продукту.
Найдите расхождения, которые у вас уже есть
Даже при хорошем процессе часть изменений проскальзывает. Эти сигналы подскажут, где:
- Обращения в поддержку со ссылкой на вашу документацию. «В инструкции сказано X, но я вижу Y» — бесплатный отчёт об ошибке. Помечайте такие обращения и исправляйте статью в тот же день.
- Поисковые запросы в центре помощи без результатов. Люди ищут название функции, которое вы переименовали, или функцию, которую никогда не документировали.
- Отзывы о статьях. Если в вашем центре помощи есть «Была ли статья полезной?», читайте комментарии к отрицательным оценкам раз в неделю. Обычно они конкретны.
- Короткая проверка самых посещаемых страниц. Раз в месяц пройдите по 20 самым просматриваемым статьям в реальном продукте. Это занимает около часа и охватывает большую часть того, что клиенты действительно читают.
Не документируйте то, что ещё не выпущено
Ловушка для быстро развивающихся команд: PR сливается за флагом функции, кто-то добросовестно обновляет документацию, и теперь центр помощи описывает функцию, которую большинство клиентов не видит. Клиенты путаются, а обращения достаются поддержке.
Придерживайте изменения документации для работы за флагом, пока флаг не включится для всех (или пишите их как черновики и публикуйте вместе с раскаткой). То же касается записей списка изменений.
Инструменты, которые помогают поддерживать документацию
У хелпдесков вроде Intercom, Zendesk и Help Scout вполне хорошие редакторы центра помощи, но они понятия не имеют, что в вашем коде, поэтому всю описанную выше связь придётся делать вам. Платформы «документация как код», такие как GitBook и Mintlify, хранят документацию в Git, что даёт проверку PR и историю, и лучше всего работают, когда ваши авторы свободно чувствуют себя в репозитории. Новые центры помощи, построенные вокруг ИИ, в том числе Ferndesk, пытаются закрыть этот разрыв с других сторон.
Мы создали Ellie Docs именно вокруг связи с PR. Вы подключаете репозиторий GitHub, и Ellie сопоставляет ваши функции и связывает каждую статью справки с функциями, которые она описывает. На каждый слитый PR она проверяет, какие статьи затрагивает изменение, и предлагает правки в виде диффа для проверки с короткой пометкой, почему. Вы принимаете или отклоняете каждое. Ничего не публикуется само.

Она также составляет черновики записей списка изменений по тем же слитым PR и придерживает всё, что ещё за флагом, до выпуска.

Всё, о чём говорится в этом материале, можно сделать вручную, и многие команды так и делают. Ellie просто каждый раз берёт на себя часть «какие статьи затрагивает этот PR и что в них нужно изменить?».
Частые вопросы
Кто должен отвечать за документацию в небольшой команде? Один названный человек отвечает за центр помощи в целом (часто основатель или тот, кто занимается поддержкой), но каждый инженер отвечает за влияние на документацию своих PR. Общая ответственность без названного владельца означает отсутствие владельца.
Как часто нужно пересматривать документацию? Непрерывно для изменений (через чек-лист в PR) плюс ежемесячный обход самых просматриваемых статей. Крупные квартальные переработки — признак того, что непрерывная часть не происходит.
Стоит ли применять «документацию как код» для справки для клиентов? Если пишут инженеры, да. Если большую часть пишут поддержка или маркетинг, обычный редактор центра помощи плюс чек-лист в PR и карта документации обычно работают лучше, чем принуждение всех к Git.
Что даст самый быстрый результат, если документация уже сильно устарела? Исправьте 10 самых посещаемых статей, добавьте шаблон PR и начните помечать обращения в поддержку, где упоминается документация. Это остановит ухудшение, прежде чем вы возьмётесь за длинный хвост.
Если хотите, чтобы обновления документации предлагались вам на каждый PR, попробуйте Ellie Docs бесплатно. Подключите репозиторий, получите черновик центра помощи и проверяйте предложенные правки по мере выпуска обновлений.