Как поддерживать документацию в актуальном состоянии, если вы выпускаете обновления каждую неделю

Автор: Fraser Hardy

Слитый pull request с красными и зелёными строками диффа и стрелка, ведущая к статье справки, где соответствующий шаг подсвечен для проверки, с кнопками «Принять» и «Отклонить»

Клиент пишет: «В вашей инструкции сказано зайти в “Настройки”, затем в “Календарь”. Никакого “Календаря” нет». Он прав. Вы перенесли его в раздел «Аккаунты» шесть недель назад. PR проверили, протестировали и выпустили. Статья справки не изменилась, потому что менять её никто не был обязан.

Так возникает почти вся устаревшая документация. Дело не в лени, а в отсутствии связи между «мы изменили продукт» и «вот статьи, описывающие изменённую часть».

Чтобы поддерживать документацию в актуальном состоянии при еженедельных выпусках, сделайте документацию частью pull request: каждый PR отвечает на вопрос «меняет ли это то, что видит клиент?», называет затронутые статьи справки и несёт правку документации в том же PR или в связанном. Затем автоматизируйте механическую часть (скриншоты, записи списка изменений) и следите за обращениями в поддержку и поисковыми запросами в центре помощи, чтобы ловить расхождения, которые проскользнули.

Остальная часть материала — о том, как настроить это без найма технического писателя.

Почему документация устаревает

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

Документация живёт в другом месте. Код в GitHub. Документация в Intercom, Zendesk, Notion или пространстве GitBook. Ничто не связывает файл в одном месте со страницей в другом, поэтому изменение в одном никогда не подталкивает заглянуть в другое.

Тот, кто знает, не тот, кто пишет. Инженер, переместивший настройки календаря, точно знает, что изменилось. Человек, который ведёт центр помощи, узнаёт об этом от клиента.

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

Никто не знает, какие статьи затронуты. Даже мотивированная команда не может проверить 80 статей после каждого выпуска. Поэтому не проверяет ни одной.

Иллюстративный график расхождения документации со временем: линия квартальной переработки падает после каждого еженедельного выпуска и возвращается вверх только при переработке, а линия обновлений по каждому PR остаётся близкой к точной всё время

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

Сделайте документацию частью определения готовности

Самое эффективное изменение: добавьте раздел о документации в шаблон 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")

Шаблон pull request с разделом «Влияние на документацию»: флажки о том, видно ли изменение пользователю, каких статей справки оно касается, нужно ли переснять скриншоты и подготовлена ли запись для списка изменений

Примерно две недели это кажется бюрократией. А потом наступает момент, когда инженер говорит: «О, в статье по онбордингу упоминается этот экран», пока контекст ещё свеж. Правка документации в две строки, написанная тем, кто внёс изменение, лучше идеальной, написанной месяц спустя наугад.

Два правила, чтобы это закрепилось:

  1. Рецензенты ставят флажок. Если PR очевидно меняет интерфейс и говорит «влияния на документацию нет», рецензент спрашивает почему. Так же, как при отсутствии теста.
  2. Правка документации может быть черновой. Инженерам не нужно писать отполированную прозу. «Шаг 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. Шаблоны смотрите в материале как писать список изменений, который читают клиенты.

Видео. Если у вас есть обучающие видео, та же карта путей кода подскажет, какие нужно перезаписать. Раздельная запись изображения и голоса ускоряет переделку; вот процесс создания обучающих видео по продукту.

Найдите расхождения, которые у вас уже есть

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

Не документируйте то, что ещё не выпущено

Ловушка для быстро развивающихся команд: PR сливается за флагом функции, кто-то добросовестно обновляет документацию, и теперь центр помощи описывает функцию, которую большинство клиентов не видит. Клиенты путаются, а обращения достаются поддержке.

Придерживайте изменения документации для работы за флагом, пока флаг не включится для всех (или пишите их как черновики и публикуйте вместе с раскаткой). То же касается записей списка изменений.

Инструменты, которые помогают поддерживать документацию

У хелпдесков вроде Intercom, Zendesk и Help Scout вполне хорошие редакторы центра помощи, но они понятия не имеют, что в вашем коде, поэтому всю описанную выше связь придётся делать вам. Платформы «документация как код», такие как GitBook и Mintlify, хранят документацию в Git, что даёт проверку PR и историю, и лучше всего работают, когда ваши авторы свободно чувствуют себя в репозитории. Новые центры помощи, построенные вокруг ИИ, в том числе Ferndesk, пытаются закрыть этот разрыв с других сторон.

Мы создали Ellie Docs именно вокруг связи с PR. Вы подключаете репозиторий GitHub, и Ellie сопоставляет ваши функции и связывает каждую статью справки с функциями, которые она описывает. На каждый слитый PR она проверяет, какие статьи затрагивает изменение, и предлагает правки в виде диффа для проверки с короткой пометкой, почему. Вы принимаете или отклоняете каждое. Ничего не публикуется само.

Предложенное Ellie Docs обновление статьи «Подключите календарь и посмотрите доступность» после слитого PR: устаревший шаг зачёркнут красным, новые шаги выделены зелёным, рядом кнопки «Принять» и «Отклонить»

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

Страница списка изменений в Ellie Docs с записями, составленными по отправленному коду, в том числе о новой панели настроек доступности; каждая запись связана со статьёй справки и готова к публикации

Всё, о чём говорится в этом материале, можно сделать вручную, и многие команды так и делают. Ellie просто каждый раз берёт на себя часть «какие статьи затрагивает этот PR и что в них нужно изменить?».

Частые вопросы

Кто должен отвечать за документацию в небольшой команде? Один названный человек отвечает за центр помощи в целом (часто основатель или тот, кто занимается поддержкой), но каждый инженер отвечает за влияние на документацию своих PR. Общая ответственность без названного владельца означает отсутствие владельца.

Как часто нужно пересматривать документацию? Непрерывно для изменений (через чек-лист в PR) плюс ежемесячный обход самых просматриваемых статей. Крупные квартальные переработки — признак того, что непрерывная часть не происходит.

Стоит ли применять «документацию как код» для справки для клиентов? Если пишут инженеры, да. Если большую часть пишут поддержка или маркетинг, обычный редактор центра помощи плюс чек-лист в PR и карта документации обычно работают лучше, чем принуждение всех к Git.

Что даст самый быстрый результат, если документация уже сильно устарела? Исправьте 10 самых посещаемых статей, добавьте шаблон PR и начните помечать обращения в поддержку, где упоминается документация. Это остановит ухудшение, прежде чем вы возьмётесь за длинный хвост.

Если хотите, чтобы обновления документации предлагались вам на каждый PR, попробуйте Ellie Docs бесплатно. Подключите репозиторий, получите черновик центра помощи и проверяйте предложенные правки по мере выпуска обновлений.