Привет! Меня зовут Марина Павлова, я технический писатель в отделе документации 1С-Битрикс. В этой статье я расскажу:
как мы полностью переделали документацию по Bitrix Framework,
что изменилось в документации для разработчиков,
как команде из двух человек удалось выпустить доку за 9 месяцев с помощью ИИ, когда мы параллельно работали над другими проектами.
Новая документация уже доступна на сайте
Какую проблему мы решали
Раньше искать информацию нужно было по разным учебным курсам и документациям. Чтобы полностью разобраться в работе какого-то компонента продукта, приходилось открывать несколько ресурсов:
курс Контент-менеджер или Администратор. Базовый, чтобы узнать основы работы с продуктом в интерфейсе,
курс Разработчик Bitrix Framework, чтобы разобраться, как работать с компонентом в фреймворке,
документацию по API, чтобы посмотреть описание классов и методов.
Такой подход позволял точечно закрывать потребности разных ролей. Но для решения комплексных задач он перестал быть эффективным. Мы собрали отзывы и поняли: нужен единый источник. Теперь мы объединяем все — от основ работы до справочника API — в рамках связанных статей.
Как ИИ помог нам ускорить работу в 2 раза
За 9 месяцев 2025 года команда из двух технических писателей выпустила 65 статей. Нейросети сэкономили нам более 400 часов — без ИИ работа заняла бы вдвое больше времени.
Какие задачи взял на себя ИИ
Анализ и реструктуризация контента. ИИ объединял старые материалы из разных курсов и предлагал новую структуру.
Генерация примеров кода. Нейросети помогали создавать рабочие примеры, анализируя исходный код продукта.
Написание комментариев. Нейросети добавляли комментарии в код, чтобы примеры были понятными.
Переработка стиля. ИИ изучил нашу редполитику. Мы отправляли ему тексты, а он предлагал, как написать лучше.
Создание контента с нуля. По некоторым темам у нас не было исходных материалов в курсах и документации. ИИ помогал писать черновики по исходному коду продукта.
Реальный пример из нашей работы — статья про JWT (JSON Web Token). Информации о работе с JWT не было в курсах и старой документации. Мы писали статью с нуля:
Передали ИИ исходный код класса BitrixMainWebJWT, заметки разработчика и желаемую структуру статьи.
Получили готовый черновик статьи, с которым можно работать.
Дали задание ИИ добавить комментарии в примеры кода, пояснить непонятные моменты для начинающих разработчиков.
Попросили нейросеть почитать статью и дать обратную связь от лица junior, middle и senior PHP-разработчиков.
Вычитали и поправили текст.
Отдали на фактчек в техническую поддержку.
На практике замечаний от технической поддержки по таким статьям пришло мало. ИИ помогает писать статьи для документации своими силами и привлекать разработчика только для проверки.
Какие нейросети мы использовали
Мы не ограничивались одной нейросетью — использовали ChatGPT, DeepSeek, Qwen и Битрикс24 Copilot. Для себя я определила оптимальное применение каждой из них:
DeepSeek — для работы с текстами,
Qwen — для проверки стиля и фактов,
ChatGPT — для работы с кодом,
Битрикс24 Copilot — для решения небольших задач в рабочем чате: отформатировать код, покритиковать небольшой текст, изменить оформление списка или таблицы и так далее.
Что меняется в новой документации
Мы сосредоточились на практической ценности. Вот ключевые изменения.
1. Вся информация по теме — в одной статье
Мы уходим от разделения по ролям: контент-менеджер, администратор, разработчик. Теперь, чтобы найти решение, не нужно открывать разные ресурсы.
Было. Чтобы настроить кеширование, вы читали о настройках админки в курсе Администратор. Базовый, изучали конфигурацию ядра в курсе Разработчика и искали описание класса в документации API D7.
Стало. В новой документации статья Кеширование содержит общее описание, административные настройки, конфигурацию в .settings.php , описание класса и готовые примеры кода. Задача решается в одном месте.
2. Актуальный контент и готовые примеры кода
Мы в процессе обновления материалов: проверяем контент, убираем устаревшую информацию и добавляем новые примеры.
Пример. Статья Создание модуля содержит пример модуля с описанием структуры и всех файлов. Его можно использовать как основу для собственного модуля.
3. Полный справочник API и наглядные форматы
В структуру документации мы добавили Справочник API с описанием классов и методов. Информация в справочнике формируется автоматически из исходного кода продукта, поэтому она всегда актуальна.
4. Обратная связь
Новая документация развивается вместе с сообществом. Мы настроили прозрачные процессы для ваших правок и комментариев.
Система оценок. Каждую статью можно оценить — полезна или не полезна. Мы анализируем количество оценок и изучаем конкретные жалобы в комментариях. Если вы ставите низкую оценку, поясните в комментарии почему. Это поможет нам понять суть проблемы и исправить документацию.
Issues. На каждой странице есть кнопка Report an issue or ask a question. Видите неточность или есть предложение — создавайте issue. Опишите суть ошибки максимально подробно и, пожалуйста, оставляйте здесь только замечания к документации, вопросы по работе с продуктом направляйте в техподдержку.
Pull Requests. Вы можете стать контрибьютором документации. Чтобы внести правки, нажмите Edit in GitHub на странице документации — откроется файл в нашем репозитории, где можно сразу предложить изменения через Pull Request.
Что планируем дальше
Это только начало пути. Мы уже работаем над переносом в новый формат других материалов из курса разработчика и документации API D7. Наша цель — создать исчерпывающий и удобный ресурс, где вы сможете найти ответ на любой вопрос по разработке на наших продуктах.
Ссылки
Новая документация
GitHub-репозиторий
Изучайте, используйте в работе и делитесь обратной связью. Ваши замечания и предложения через issues, pull requests или комментарии помогут нам улучшить документацию.
Источник: habr.com
