Docs as Code для выпуска и обновления документации

Docs as Code («документация как код») — подход к документации, в котором используют инструменты и процессы разработки программ. Исходные тексты хранят в системе контроля версий, изменения обсуждают перед включением в общую редакцию, а сайт документации или файлы для передачи собирают из этих исходников. Обычно для этого применяют Git, текстовую разметку и автоматические проверки.

Начинать стоит с выбора материалов и порядка работы, а не с установки генератора сайта. Определите, кто меняет документ, кто сверяет его с продуктом и какая редакция должна сопровождать выпуск. Затем проверьте процесс на одном руководстве или инструкции.

Подход удобен для продуктовой документации, которая регулярно меняется вместе с программой. Он требует поддержки инструментов и обучения авторов. Успешная сборка подтверждает техническую готовность файлов; соответствие описанных действий выпущенной версии проверяют отдельно.

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

В описании Write the Docs ↗ к подходу относятся контроль версий, текстовая разметка, рассмотрение изменений и автоматические проверки. Сохранение нескольких файлов в Git само по себе ещё не задаёт такой процесс: нужны правила совместной работы и выпуска.

Выбор между Git, wiki и смешанным вариантом

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

В смешанном варианте не нужно вручную поддерживать одинаковую инструкцию в двух местах. Можно хранить исходник в Git и публиковать из него сайт, а в wiki оставить ссылку, обсуждение и решения. Если авторы редактируют wiki, обратный перенос в репозиторий должен быть частью установленного процесса, иначе появятся расходящиеся редакции.

Для небольшого стабильного комплекта стоимость перехода может оказаться выше пользы. Обучение, перенос изображений, настройка прав и обслуживание сборки — тоже работа. Условия внедрения и связанные трудности разобраны в опыте создания портала документации Plesk ↗.

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

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

Минимальный набор инструментов

Нужны хранилище исходников, средство подготовки текста, просмотр предлагаемой правки и способ получить готовую документацию. Markdown и AsciiDoc — распространённые варианты текстовой разметки; выбирать их стоит с учётом таблиц, перекрёстных ссылок, изображений и требуемых выходных форматов.

Сначала проверьте ограничения на одном материале. Если в поставке нужен файл в переносимом формате документов (PDF), попробуйте получить его с оглавлением, таблицами, кириллицей и рабочими ссылками. Наличие красивого сайта не подтверждает пригодность печатного файла. Если авторы работают без доступа в интернет, проверьте доступность зависимостей и сборки в их среде.

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

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

От изменения продукта к правке текста

1. Определите, что затронуто. Найдите страницы, изображения и вложения, зависящие от изменённой функции. Если пользовательские действия и условия остались прежними, допустим результат проверки без переписывания текста.
2. Подготовьте связанную правку. Объясните, какое поведение изменилось и для какого выпуска. Вместе с основным разделом обновите необходимые изображения, ссылки и выходные файлы.
3. Дайте проверяющему готовое представление. Одного сравнения строк недостаточно, чтобы заметить обрезанную таблицу или нечитаемую схему. Предварительный просмотр должен соответствовать способу чтения материала.
4. Проверьте содержание. Выполните описанную операцию или сверьте сведения с подходящим подтверждением. Запишите версию, условия, результат и оставшиеся ограничения.
5. Выпустите принятую редакцию. Свяжите публикацию с версией продукта и сохраните требуемый экземпляр. Проверьте, что читатель действительно получает эту редакцию по рабочей ссылке.

В процессе GitLab ↗ изменения документации связываются с изменениями продукта и проходят проверку. Это полезный ориентир; конкретные роли и сроки GitLab не становятся обязательными правилами другой команды.

Два разных основания для выпуска

Автоматические проверки могут обнаружить ошибку разметки, недоступную ссылку или неудачную сборку. Проверка разметки и ссылок не устанавливает, что названная кнопка доступна нужной роли, а описанная функция уже выпущена. Для этого требуется проверка по продукту и условиям применения; часть таких проверок тоже можно автоматизировать.

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

Пока применимость необходимого раздела не подтверждена, его нельзя представлять как проверенный для новой версии. Исправьте его либо явно ограничьте применение. Если документация входит в согласованный состав поставки, порядок передачи и изменения этого состава нужно решать отдельно: редакторское предупреждение не меняет обязательств.

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

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

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

Поддерживаемые версии и зафиксированный комплект

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

В Read the Docs ↗ версии документации связывают с ветвями и тегами Git. Это пример реализации, а не требование выбрать платформу. Важно, чтобы читатель отличал документацию выпущенной версии от описания ещё разрабатываемых изменений.

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

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

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

Признаки работающего процесса

• Автор и проверяющий могут найти исходник, понять правку и увидеть готовое представление.
• Есть основание считать документ применимым к указанной версии; непроверенные части обозначены.
• Сайт и передаваемые файлы получают из принятой редакции без неучтённой ручной правки.
• Для ошибки известны ответственный, способ исправления и необходимая повторная проверка.
• Предыдущий переданный экземпляр можно восстановить независимо от текущей страницы.

Ошибки, которые стоит предупредить

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

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

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

Что дальше

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