Начинайте не с Git, а с проблемы
Docs-as-Code часто продают как набор инструментов: Markdown, Git, pull request, CI, статический генератор. Команда начинает спорить о редакторах и ветках раньше, чем формулирует проблему, ради которой вообще затевается изменение процесса.
Git может быть здесь ни при чём. Гораздо полезнее сначала записать наблюдаемые симптомы.
| Что происходит сейчас | Какая проблема за этим стоит |
|---|---|
| Никто не уверен, какая версия инструкции актуальна | Нет единого канонического источника и понятной истории изменений |
| Изменение продукта выходит раньше документации | Документация не встроена в release process |
| Эксперт получает на ревью сорок страниц | Ревью не показывает изменение в контексте и заставляет перечитывать лишнее |
| Один термин пишут тремя способами | Нет контролируемой терминологии или автоматической проверки |
| Битую ссылку первым находит клиент | Проверка происходит слишком поздно |
| Публикация зависит от одного ноутбука | Сборка и выпуск не воспроизводятся |
Docs-as-Code имеет смысл, когда конкретный симптом становится измеримо слабее. Если автору стало тяжелее писать, эксперту — тяжелее проверять, а выпуск по-прежнему ручной, новый стек просто заменил старое неудобство новым.
Из чего на самом деле состоит Docs-as-Code
Git — только один слой. Полезнее смотреть на весь путь материала от изменения продукта до публикации.
| Этап | Что происходит | Простой вариант | Более зрелый вариант |
|---|---|---|---|
| 1. Исходник | Автор меняет текст | Markdown/AsciiDoc в репозитории | Структурированный контент + схема метаданных |
| 2. Редактирование | Автор работает с файлом | Веб-редактор GitHub | github.dev, VS Code, IDE или специализированный authoring UI |
| 3. Предпросмотр | Автор видит будущую страницу | Локальная/веб-сборка | Preview для каждой ветки или изменения |
| 4. Автопроверки | Машина ловит рутину | Ссылки + сборка | Стиль, термины, схема, accessibility, примеры API, локализации |
| 5. Ревью | Человек проверяет смысл | Один рецензент | Раздельно SME + редактор/техпис |
| 6. Слияние | Изменение становится каноническим | Commit в основную ветку | Protected branch + checks + approval |
| 7. Публикация | Сайт обновляется | Ручная сборка | CI/CD после успешных проверок |
| 8. Контроль после релиза | Проверяется опубликованная версия | Ручная выборка | Link check, smoke test, мониторинг ошибок |
Смысл подхода не в том, чтобы каждый столбец довести до максимальной сложности. Команда выбирает минимальную достаточную ступень на каждом этапе.
Текстовый формат не означает обязательную IDE
Фраза «храним документацию в Git» почему-то часто превращается в «теперь все должны писать в VS Code и знать терминал». Связи между этими утверждениями нет.
У GitHub есть обычный файловый редактор в браузере: открыли Markdown-файл, нажали редактирование, внесли изменения и сохранили commit. Для более длинной работы есть github.dev: он тоже работает в браузере, даёт поиск по репозиторию, подсветку синтаксиса и управление изменениями, но не требует локального clone. Открыть его можно прямо из репозитория или клавишей ..
Поэтому интерфейс автора можно выбирать по роли:
| Кто редактирует | Что ему обычно достаточно | Чего не стоит требовать без причины |
|---|---|---|
| Техпис каждый день | github.dev, VS Code или привычный редактор |
Конкретную IDE только потому, что ею пользуются разработчики |
| SME раз в месяц | GitHub web editor + preview | Терминал, rebase, локальную сборку |
| Разработчик | IDE + Git | Отдельную CMS, если ему удобнее менять Markdown рядом с кодом |
| Редактор | Browser editor или authoring UI | Знание внутреннего устройства pipeline |
| Переводчик | Веб-интерфейс/локализационный слой | Ручное управление ветками для каждой строки |
Хороший Docs-as-Code разделяет формат хранения и интерфейс редактирования. Канонический исходник может оставаться текстовым и версионируемым, а участники получают настолько простой вход, насколько позволяет их задача.
Как выглядит нормальный рабочий процесс
Для продуктовой документации чаще всего достаточно такого пути:
previewбудущая страницаbuild / links / termsmerge и публикацияCI/CD + smoke checkВ маленькой команде несколько ролей может выполнять один человек. Создавать pull request ради ритуала не требуется, если автор и издатель совпадают, а риск изменения низкий. Автоматическая сборка и несколько полезных проверок перед публикацией всё равно сохраняют смысл.
В большой команде роли лучше разделить. SME отвечает за факты: действительно ли endpoint принимает параметр, действительно ли кнопка называется именно так, действительно ли ограничение действует. Техпис отвечает за задачу пользователя, структуру, терминологию и понятность. Машина отвечает за то, что можно проверить однозначным правилом.
Какие проверки имеет смысл автоматизировать
Автоматизация полезна там, где вопрос можно сформулировать как «да/нет» или сравнить с формальным правилом.
| Проверка | Что ловит | Когда запускать | Что должна показать ошибка |
|---|---|---|---|
| Сборка | сломанный синтаксис, include, template | каждый change | файл и конкретную строку/причину |
| Внутренние ссылки | удалённые страницы, неверные anchors | каждый change | исходную и целевую ссылку |
| Внешние ссылки | 404/410, redirect loops | по расписанию | URL и статус; не блокировать релиз из-за случайного timeout |
| Frontmatter/metadata | нет title, owner, locale, revision | каждый change | отсутствующее или неверное поле |
| Структура | пропущенный H1/H2, неверная вложенность | каждый change | какой heading нарушает правило |
| Терминология | запрещённые/устаревшие термины | каждый change | термин и рекомендуемая замена |
| Style lint | пассив, лишние клише, запрещённые формулировки | каждый change | короткое объяснение, а не сотню однотипных warning |
| Code examples | синтаксис, формат, иногда выполнение | каждый change | какой пример не проходит и почему |
| API contract | пример расходится со схемой/OpenAPI | при изменении API-доков | поле/endpoint, который больше не совпадает |
| Изображения | отсутствующий файл, alt, слишком большой asset | каждый change | имя изображения и нарушение |
| Accessibility | часть формальных HTML/Markdown-паттернов | сборка/preview | конкретный элемент, требующий проверки |
| Локализации | нет обязательного языка или revision расходится | каждый change | язык и статья, которые отстали |
| Секреты и PII | случайный token, ключ, пароль, персональные данные | каждый change | тип находки без публикации секрета в лог |
| Дубли | повторённый большой фрагмент | каждый change/периодически | обе страницы, где найдено совпадение |
Предупреждение, которое никто не собирается исправлять, нужно сделать полезным или удалить. Сотни сообщений не показывают зрелость pipeline; они только учат команду переставать читать результаты проверки.
Сколько времени это может сэкономить
У Docs-as-Code нет честной универсальной цифры «экономит 37% времени». Разные команды начинают с разных процессов. В смежных исследованиях промышленного code review видно, что автоматизация повторяемых проверок и исправлений действительно снимает заметную часть ручной работы, но переносить конкретный процент из разработки на документацию было бы некорректно.
Полезнее считать эффект на собственном процессе. Ниже приведён расчётный пример, а не отраслевой benchmark. Допустим, команда выпускает 40 изменений документации в месяц, а ручная проверка ссылок, метаданных, терминов, сборки и базовой структуры занимает в среднем 20 минут на изменение. За месяц накапливается 800 минут, или 13 часов 20 минут активной рутины. Если после автоматизации автор тратит около 2 минут на просмотр результата и исправление найденных нарушений, тот же объём занимает примерно 1 час 20 минут. При таких исходных данных освобождается около 12 часов в месяц.
Допущение: 40 изменений × 20 минут ручной рутины против 40 × 2 минуты на разбор результатов. Расчёт нужен для планирования эксперимента и не является опубликованной статистикой рынка.
График полезен только вместе с допущениями. Если у вас пять изменений в месяц, экономия будет другой. Если link checker создаёт десять ложных тревог на каждый commit, автоматизация может вообще увеличить время.
Как измерить эффект у себя, а не придумать «исследование»
Мы не должны писать «TechWriters исследовал несколько проектов и доказал экономию», пока такого исследования действительно нет. Зато его несложно провести нормально.
На двух–пяти проектах в течение четырёх недель фиксируйте для каждого изменения:
- активное время автора от начала правки до готовности к ревью;
- время ожидания review;
- активное время SME и редактора;
- число замечаний, которые могла бы поймать машина;
- число ошибок, найденных уже после публикации;
- время от готового текста до production;
- количество ложных срабатываний автоматических проверок.
Потом автоматизируйте один класс проблем — например ссылки, metadata и build — и повторите измерение. Сравнение даст материал, в котором можно честно показать объём проектов, изменение метрик, пользу автоматизации и количество добавленного шума. Измеренный результат намного ценнее красивой выдуманной цифры.
Человек и автоматика должны проверять разное
Плохой pipeline пытается автоматизировать всё. Хороший снимает с людей рутину, чтобы они тратили внимание там, где требуется суждение.
| Машина хорошо проверяет | Человек должен проверять |
|---|---|
| существует ли ссылка | ведёт ли она туда, куда действительно нужно пользователю |
| есть ли обязательный heading | правильно ли материал разбит по задачам |
| разрешён ли термин | понятен ли термин именно этой аудитории |
| совпадает ли пример со схемой | объясняет ли пример реальную задачу |
заполнено ли поле updated |
действительно ли материал актуален |
| собирается ли страница | помогает ли она человеку выполнить работу |
Такое разделение особенно важно сейчас, когда к обычным линтерам добавляются LLM-проверки. ИИ может искать противоречия, предлагать редактуру и находить подозрительные места, но факт должен подтверждаться продуктом, спецификацией, тестом или ответственным экспертом, а не уверенностью модели.
Где начинается фанатизм
Фанатизм начинается не с Git, а в момент, когда чистота процесса становится важнее результата и людей.
Если эксперт может за две минуты исправить название параметра в браузере, не заставляйте его ставить Node.js, клонировать repository, создавать branch и разбираться с конфликтом. Если техпису удобно работать в VS Code — не заставляйте его использовать упрощённую форму. Если публикация требует review, оставьте review. Если простая опечатка в маленькой команде безопасно проходит через автоматические checks и прямой commit — не создавайте церемонию ради картинки «как у разработчиков».
У команды должен быть escape hatch: браузерное редактирование, шаблон задачи, assisted authoring или человек, который принимает изменение и проводит его через Git. Канонический процесс остаётся контролируемым, но вход в него не обязан быть одинаковым для всех.
Как внедрять Docs-as-Code поэтапно
Итак, какой план действий? Начните с одного репозитория и одного типа документации, не покупая новый стек заранее.
На первую неделю хватит переноса исходников в Git. Заодно убедитесь, что команда умеет открыть файл, посмотреть историю и внести небольшую правку хотя бы через браузер. Терминал на этом этапе никому не обязан быть нужен.
На второй неделе добавьте preview и автоматический build. Автор должен увидеть будущую страницу до публикации и получить понятную ошибку, если сборка сломалась.
Третью неделю отдайте нескольким проверкам, которые уже ловили реальные проблемы проекта: broken links, обязательные metadata, терминология, build, полнота локализаций. Три полезных проверки лучше тридцати предупреждений, к которым все привыкли.
На четвёртой неделе посмотрите, где действительно нужно отдельное техническое и редакторское ревью. Для изменения API участие SME оправдано; для исправления опечатки дополнительная церемония может только замедлить выпуск.
Через месяц измерьте lead time, ручную рутину, ошибки после публикации и ложные срабатывания. Следующий слой автоматизации имеет смысл добавлять только после такого сравнения.
Docs-as-Code работает, когда автору проще внести изменение, эксперту проще проверить факт, редактору проще увидеть смысловую проблему, а пользователю быстрее достаётся актуальная страница. Красота схемы в README к результату отношения не имеет.
