Написание технической документации для 1С-Битрикс
Разработчик уходит, а следующий тратит три недели, чтобы понять, как работает нестандартный компонент синхронизации с 1С. Обновление ядра Битрикс ломает кастомный модуль, потому что никто не записал, какие хуки он использует. Нет документации — нет передаваемости: каждая команда начинает с нуля. На Битрикс-проектах ситуацию осложняет смесь старого ядра, D7 API и кастомных модулей — без описания непонятно даже, что где лежит.
Что документируем на Битрикс-проекте
Архитектура проекта:
- Структура директорий: что лежит в
/local/, какие кастомные модули в/local/modules/, где шаблоны сайтов - Используемые редакции и версии: Битрикс, PHP, СУБД, ОС
- Схема серверной инфраструктуры (если не одна машина)
- Список сторонних библиотек (Composer, npm)
Модули и компоненты: Для каждого кастомного модуля: назначение, список публичных методов, используемые хуки событий, зависимости от других модулей, таблицы БД.
Интеграции: Для каждой внешней интеграции: какая система, механизм (API, CommerceML, вебхуки), параметры подключения (где хранятся ключи), расписание, что делать при падении.
Деплой и обслуживание: Пошаговая инструкция развёртывания на чистом сервере, порядок обновления ядра Битрикс, процедура отката.
Стандарты документирования кода
Для PHP — PHPDoc-блоки на всех публичных методах:
/**
* Резолвит артикул в 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 не поддерживает блокирующие чтения в текущей версии Битрикс
Формат документации
README.md — первый файл, который открывает новый разработчик. Структура:
- Что за проект, какие задачи решает
- Требования (PHP, расширения, СУБД)
- Установка за 5 шагов
- Структура проекта
- Ссылки на детальную документацию
Документация API — если проект предоставляет REST API, документируем в формате OpenAPI 3.0 (openapi.yaml). Для внутренних AJAX-контроллеров Битрикс достаточно таблицы эндпоинтов с параметрами и примерами ответов.
Руководство администратора — для редакторов и менеджеров: как добавить товар, настроить акцию, посмотреть заказы. Скриншоты административного раздела Битрикс с аннотациями.
Инструменты и хранение
Документация хранится рядом с кодом — в репозитории Git, директория /docs/. Это гарантирует версионирование и доступность для всей команды. Для тяжёлых руководств с изображениями — Confluence или Notion с синхронизацией с репозиторием.
Актуальность — самая большая проблема документации. Решение: документирование как часть Definition of Done: задача не закрыта, пока не обновлена соответствующая страница документации.
Что входит в написание документации
- Аудит существующей документации и выявление пробелов
- Написание архитектурного описания проекта (структура, модули, интеграции)
- Документирование кастомных модулей и нестандартных компонентов
- Описание всех интеграций с параметрами и процедурами восстановления
- Инструкции по развёртыванию и обслуживанию
- Руководство пользователя административного раздела