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