Написание технической документации для 1С-Битрикс

Разработчик уходит, а следующий тратит три недели, чтобы понять, как работает нестандартный компонент синхронизации с 1С. Обновление ядра Битрикс ломает кастомный модуль, потому что никто не записал, какие хуки он использует. Нет документации — нет передаваемости: каждая команда начинает с нуля. На Битрикс-проектах ситуацию осложняет смесь старого ядра, D7 API и кастомных модулей — без описания непонятно даже, что где лежит. Мы сталкиваемся с такими проектами постоянно и знаем, как систематизировать хаос.

Почему документация критична для Битрикс-проектов?

Без документации каждый новый разработчик тратит от 40 часов на изучение кода. Аудит типичного Битрикс-проекта показывает, что 60% кастомного кода не покрыто комментариями. Это увеличивает время на багфикс в 3 раза по сравнению с документированным проектом. Документация — это инвестиция, которая окупается при первом же обновлении ядра или смене разработчика. Проект с документацией в Git/docs/ обновляется в 2 раза быстрее, чем с разрозненными заметками.

Что мы документируем на Битрикс-проекте

Перечислим ключевые блоки, которые обязательно должны быть описаны:

• Архитектура проекта: структура директорий в /local/, кастомные модули в /local/modules/, шаблоны сайтов, используемые редакции и версии (Битрикс, PHP, СУБД, ОС), схема серверной инфраструктуры, список сторонних библиотек (Composer, npm).
• Модули и компоненты: назначение, публичные методы, используемые хуки событий, зависимости, таблицы БД. Обязательно с PHPDoc-блоками.
• Интеграции: механизм (API, CommerceML, вебхуки), параметры подключения, расписание, процедура восстановления при падении.
• Деплой и обслуживание: пошаговая инструкция развёртывания на чистом сервере, порядок обновления ядра, процедура отката.

Сравнение форматов документации

Рекомендуем комбинировать подходы: главное README в репозитории и детальная документация в Confluence для командной работы и обновлений.

Структура типового README.md

/**
 * Резолвит артикул в ID торгового предложения.
 *
 * @param  string $article  Артикул товара (свойство PROPERTY_CML2_ARTICLE)
 * @param  int    $iblockId ID инфоблока торговых предложений
 * @return int|null         ID оффера или null, если не найден
 *
 * @throws \Bitrix\Main\ArgumentException При некорректном iblockId
 */
public function resolveArticle(string $article, int $iblockId): ?int

Для нестандартных решений — инлайн-комментарий «почему», а не «что»:

// Используем SELECT FOR UPDATE здесь, а не ORM, потому что
// DataManager не поддерживает блокирующие чтения в текущей версии Битрикс

Мы придерживаемся стандартов Официальной документации 1С-Битрикс для PHPDoc.

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

Как мы гарантируем актуальность документации?

Актуальность — самая большая проблема документации. Наше решение: документирование становится частью Definition of Done. Задача не закрыта, пока не обновлена соответствующая страница документации. Мы также проводим регулярные аудиты документации каждые три месяца. На практике это означает, что каждый разработчик тратит 30 минут на документирование своих изменений, но экономит недели при работе новых членов команды. Это инвестиция в будущее проекта, которая особенно критична при плановых обновлениях Битрикс.

Что входит в услугу

• Аудит существующей документации и выявление пробелов
• Написание архитектурного описания проекта (структура, модули, интеграции)
• Документирование кастомных модулей и нестандартных компонентов
• Описание всех интеграций с параметрами и процедурами восстановления
• Инструкции по развёртыванию и обслуживанию
• Руководство пользователя административного раздела

Как мы работаем

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

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

Документация проектов на 1С-Битрикс

Разработчик уволился. Новый открывает init.php на 2000 строк — видит 47 обработчиков событий через AddEventHandler, цепочку агентов в b_agent и кастомный модуль без единого комментария. На вникание уходит месяц. Документация этот месяц превращает в три дня. Мы создаём её для проектов на 1С-Битрикс: от архитектурных схем до пошаговых инструкций для контент-менеджера.

Наличие документации сокращает время адаптации нового разработчика в три раза — с трёх недель до одной. Без неё каждый второй проект сталкивается с даунтаймом при обновлении ядра или сбоях обмена с 1С. Более 10 лет опыта разработки на Битрикс и 50+ задокументированных проектов — это наш стандарт. Получите консультацию по вашему проекту: мы оценим объём работ за один день.

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

Конкретные ситуации, которые видим на каждом втором проекте:

• Обновление ядра — разработчик запускает bitrix/tools/upgrade.php. Обновление перезаписывает модифицированные файлы в /bitrix/components/bitrix/. Никто не знает, какие компоненты были изменены. Сайт сломался. Откат — из бекапа. Даунтайм — 4 часа.
• Обмен с 1С — агент обмена CCatalogImport::PreGenerateXML падает с ошибкой. Настройка нестандартна. Кто менял маппинг свойств? Без документации — реверс-инжиниринг на полдня.
• Новый подрядчик — команда получает проект с 12 highload-блоками без описания назначения, кастомными таблицами b_custom_order_log и b_product_sync_history. Назначение и связи с инфоблоками нигде не зафиксированы. Это затягивает ввод нового разработчика на две недели.
• Рост команды — каждый новый разработчик три недели ходит за «тем, кто знает», вместо того чтобы открыть документацию и работать.

Как структурировать документацию для разработчиков?

Техническая документация

Для разработчиков и DevOps — внутреннее устройство проекта:

Архитектура:

• Используемые модули Битрикс (sale, catalog, iblock, main, кастомные)
• Путь запроса: HTTP → nginx → urlrewrite.php → компонент → шаблон → ответ
• Серверная инфраструктура: конфигурация, топология, балансировка

Структура данных — самая критичная часть:

• Инфоблоки: типы (IBlock::TYPE_ID), разделы, свойства (PROPERTY_CODE), связи между инфоблоками через свойство типа «Привязка к элементам»
• Highload-блоки: таблица b_hlblock_entity, назначение каждого блока, структура полей, пользовательские поля (UF_*), индексы
• Кастомные таблицы в БД — зачем создавались, DDL, связи с b_iblock_element, b_sale_order и другими штатными таблицами
• Торговый каталог: типы цен (b_catalog_group), склады (b_catalog_store), правила корзины (b_sale_discount)

Кастомные разработки:

• Компоненты в /local/components/ — назначение, class.php, входные параметры (.parameters.php), шаблоны, зависимости
• Модули в /local/modules/ — API, события, установочные скрипты
• Обработчики событий — список всех AddEventHandler/registerEventHandler с описанием: какое событие, что делает, критичность
• Агенты (b_agent) — расписание, функционал, какие нельзя останавливать (обмен с 1С, рассылки, очистка корзин)
• Изменённые файлы ядра — полный список. При обновлении bitrix/ эти файлы будут перезаписаны

Интеграции:

• Обмен с 1С: настройки модуля catalog → «Обмен с 1С», формат CommerceML, расписание CCatalogImport, маппинг свойств, подводные камни (кодировки, таймауты, размер import.xml)
• Платёжные системы: обработчики в sale.handlers, режимы работы (тест/бой), URL для callback
• Службы доставки: профили в sale.delivery, алгоритмы расчёта, API-ключи
• CRM, маркетплейсы, внешние API: эндпоинты, механизмы аутентификации, частота синхронизации

Пользовательские инструкции

Для контент-менеджеров и администраторов:

Руководство контент-менеджера:

• Управление каталогом: создание элементов инфоблока, заполнение свойств, работа с разделами. Какие поля обязательны, какие влияют на отображение на сайте
• Изображения: допустимые размеры (авторесайз настроен или нет?), форматы, процесс загрузки в DETAIL_PICTURE и PROPERTY_GALLERY
• Акции и скидки — как настроить правило корзины в «Маркетинг» → «Правила работы с корзиной», не сломав ценообразование. Проверка через тестовый заказ

Руководство администратора:

• Пользователи: группы (b_group), права доступа к модулям и инфоблокам
• Обработка заказов: статусы (b_sale_status), оплата, возвраты
• Бекап через «Настройки» → «Резервное копирование» — с оговоркой, что для больших проектов штатный бекап не справляется

Формат:

• Пошагово с нумерацией
• Скриншоты с аннотациями — стрелки, выделения, подписи
• FAQ из реальных вопросов, собранных при обучении
• Видеоинструкции для нетривиальных операций (по запросу)

API-документация

Для проектов с кастомным REST API — мы описываем все эндпоинты: метод, URL, назначение, параметры (обязательные/опциональные), формат ответа. Аутентификация: механизм получения токена, TTL, обновление. Rate limiting: лимиты, HTTP-коды при превышении. Примеры — рабочие cURL-команды, не теоретические. Инструменты: Swagger/OpenAPI (согласно стандарту REST API) и Postman Collection для тестирования.

Архитектурные схемы

Одна схема заменяет 10 страниц текста. Форматы: Draw.io, Mermaid (версионируется в Git), PlantUML.

• Инфраструктура — серверы, сети, балансировщик, БД (master-slave?), Redis, CDN. Физическая и логическая топология
• Компоненты — модули Битрикс, кастомные компоненты в /local/, внешние сервисы, связи
• ER-диаграмма — таблицы b_iblock_element, b_sale_order, highload-блоки, кастомные таблицы. Поля, связи, индексы. Особенно критично для кастомных таблиц, которых нет в документации Битрикс
• Потоки данных — как информация движется между Битрикс, 1С, маркетплейсами, CRM, платёжными системами
• Карта сайта — что инфоблок, что статическая страница, что кастомный раздел на компоненте

Регламенты эксплуатации

Деплой:

• Пошаговая инструкция для staging и production
• Чек-лист после деплоя: проверка главной, каталога, чекаута, обмена с 1С
• Процедура отката — какой symlink переключить, какой бекап БД восстановить

Бекапы:

• Расписание: БД, upload/, конфигурации
• Где хранятся и сколько
• Процедура восстановления — проверенная, не теоретическая
• Тестовое восстановление раз в месяц

Обновление ядра:

• Staging → тестирование → production. Строго в таком порядке
• Проверка совместимости кастомных компонентов и изменённых файлов ядра
• bitrix/updates/ — что было обновлено

Инциденты:

• Классификация: сайт недоступен / ошибки 500 / сломался обмен с 1С / тормозит
• Контактные лица и зоны ответственности
• Шаблоны действий для каждого типа

Что входит в работу

Мы готовим полный комплект документации для вашего проекта:

• Техническая документация с описанием архитектуры, структуры данных, кастомных разработок и интеграций
• Пользовательские инструкции для контент-менеджеров и администраторов
• API-документация в формате Swagger/OpenAPI с Postman-коллекцией
• Архитектурные схемы (инфраструктура, ER-диаграммы, потоки данных)
• Регламенты эксплуатации (деплой, бекапы, обновление ядра, инциденты)
• Размещение в Confluence, GitBook, Notion или Wiki с разграничением доступа
• Гарантия актуальности — обновляем документацию при каждом значимом изменении

Сроки

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