Documentation as Code: как мы создали новую версию документации для Rest API
Программный комитет ещё не принял решения по этому докладу
Целевая аудитория
Тезисы
1. Типичные проблемы документации API и необходимость эволюции
Техническая документация API часто становится узким местом из-за ручного обновления, сложностей с синхронизацией и отсутствия стандартизации. Эти проблемы требуют перехода к автоматизированным процессам и интеграции документации в цикл разработки.
2. Ключевые требования разработчиков к документации
Современные разработчики ожидают от документации полноты описания методов, готовых примеров кода на разных языках и удобной навигации. Не менее важна возможность сообщества участвовать в улучшении материалов.
3. Documentation as Code: принципы и инструменты
Хранение документации в markdown-формате в Git-репозиториях позволяет применять практики разработки: контроль версий, code review и автоматизированную сборку. Это превращает документацию в часть продукта, а не в отдельный ресурс.
4. Автоматизация и стандартизация контента
Четкие шаблоны описания методов и автоматическая генерация примеров кода снижают нагрузку на технических писателей. Экспертная проверка изменений перед публикацией обеспечивает качество и согласованность материалов.
5. Вовлечение сообщества через открытый контрибьюшн
Разрешение разработчикам вносить правки через pull request'ы ускоряет исправление ошибок и обогащает документацию реальными кейсами. Такой подход требует чётких правил, но значительно повышает актуальность материалов.
6. Локализация и работа с ИИ-инструментами
Автоматический перевод с помощью языковых моделей упрощает локализацию, но требует проверки технических терминов. Скриншоты и специфичный контент остаются ручной задачей, но их обновление становится проще благодаря версионности.
7. Эффективность подхода и ключевые инсайты
Как показала практика, переход на «Documentation as Code» ускоряет обновление документации и повышает ее качество. Тем не менее, успех зависит от интеграции процессов в workflow команды, а не только от выбора инструментов.
8. Documentation as Code как часть DevRel-стратегии
Такой подход делает документацию динамичным ресурсом, соответствующим принципам DevRel: прозрачность, вовлечение сообщества и измеримая эффективность. Это превращает её в важную часть продукта, а не просто в справочник.
Сергей Востриков — руководитель направления Маркетплейс и интеграций в Битрикс24.
Занимается развитием функционала Битрикс24 для разработчиков тиражных решений и индивидуальных кастомизаций — REST API, документации, витрины Битрикс24 Маркет, кабинета разработчика решений, интеграционными сценариями и др. Обладает экспертизой в области разработки, продукта и продаж.
Регулярно выступает в качестве спикера на вебинарах и внутренних мероприятиях Битрикс24.
Видео
Другие доклады секции
Основной трек
