Проект сдан, магазин работает, отношения с подрядчиком отличные — зачем думать о документации? А потом команда разработки распадается, ключевой специалист уходит, или бизнес решает сменить подрядчика — и выясняется, что никто, кроме прежних разработчиков, не знает, как устроен сайт, где лежат доступы и почему обмен с 1С настроен именно так. Заказчик оказывается заложником собственного проекта.
Эта статья — о том, какая документация должна остаться у заказчика после разработки сайта на 1С-Битрикс, чтобы бизнес не зависел от одной команды. Разберём, что критично получить, как это закрепить в договоре и чего документировать не нужно. Материал основан на нашей практике передачи и приёмки проектов, в том числе через аудит унаследованных сайтов.
Коротко
- Документация — это страховка независимости бизнеса от подрядчика, а не бюрократия; её собирают, пока всё хорошо.
- Критичнее всего доступы и права: сайт, хостинг, домен, репозиторий, лицензия 1С-Битрикс должны принадлежать заказчику.
- Документируют нестандартное: кастомные модули, доработки, логику обмена с 1С, процесс деплоя — а не типовое поведение Битрикса.
- Требование о документации закрепляют в договоре как часть сдачи этапов, иначе её не напишут никогда.
Почему документация — это про независимость
Документация проекта редко воспринимается как ценность — до первого кризиса. Пока подрядчик рядом и всё работает, кажется, что описывать нечего: любой вопрос решается звонком. Но именно эта лёгкость и есть ловушка: бизнес незаметно попадает в полную зависимость от одной команды.
Реальная ценность документации проявляется в критических ситуациях:
- Смена подрядчика. Новая команда должна разобраться в проекте без помощи прежней — быстро и без реверс-инжиниринга.
- Уход ключевого специалиста. Знания не должны уходить вместе с человеком.
- Передача внутрь. Бизнес забирает поддержку в свой отдел и должен понимать, что получил.
- Срочный инцидент. Проблему нужно решить, а прежнего разработчика нет на связи.
Документацию собирают заранее, пока всё хорошо, — потому что когда станет плохо, собирать её будет уже некому и некогда.
Доступы и права: фундамент контроля
Самая критичная часть — не тексты и схемы, а доступы. Если административные права и лицензии оформлены на подрядчика, а не на заказчика, любой конфликт превращается в потерю контроля над проектом. Это первое, что нужно проверить и переоформить на себя.
| Актив | На кого должен быть оформлен | Риск при отсутствии |
|---|---|---|
| Домен | Юрлицо заказчика | Потеря адреса сайта |
| Хостинг / сервер | Аккаунт заказчика | Невозможность миграции |
| Лицензия 1С-Битрикс | Заказчик | Проблемы с обновлениями и поддержкой |
| Репозиторий кода | Организация заказчика | Потеря исходников |
| Админка сайта | Заказчик как владелец | Зависимость от подрядчика |
| Платёжные системы | Заказчик | Разрыв приёма оплат |
Описание архитектуры проекта
Следующий уровень — понимание, как устроен проект в целом. Новому разработчику нужна карта, чтобы не изучать сайт методом раскопок. Архитектурное описание отвечает на вопрос «из чего состоит проект и как части связаны».
- Структура инфоблоков. Какие инфоблоки за что отвечают, их свойства и связи — основа каталога и контента.
- Ключевые компоненты и шаблоны. Где кастомные компоненты, какие шаблоны используются, за что отвечают.
- Внешние интеграции. С какими системами связан сайт: 1С, оплата, доставка, аналитика.
- Нестандартные решения. Что и почему сделано не по типовому пути 1С-Битрикс.
Архитектурное описание не должно быть романом. Достаточно понятной карты, по которой новый специалист сориентируется за часы, а не за недели.
Кастомизации и доработки
Сердце технической документации — описание того, что отличает ваш проект от типового 1С-Битрикс. Именно кастомизации отнимают у нового разработчика больше всего времени, если не описаны, потому что их нельзя найти в официальной документации.
Что обязательно документировать:
- Кастомные модули. Что делают, где лежат, как настраиваются, от чего зависят.
- Доработки компонентов. Какие штатные компоненты изменены и в чём отличие от оригинала.
- Бизнес-логика. Нетривиальные правила: расчёт цен, скидок, доставки, статусов заказа.
- Обработчики событий и агенты. Что срабатывает автоматически, когда и зачем.
Хорошо, когда кастомная разработка изначально ведётся аккуратно — модулями, а не хаотичными правками ядра. О правильном подходе к разработке модулей мы пишем в статьях про разработку модуля 1С-Битрикс и работу с D7 ORM. Аккуратный код и сам по себе документирует проект лучше, чем километры описаний.
Документация обмена с 1С
Обмен с 1С — одна из самых важных и самых хрупких частей проекта, поэтому её документируют отдельно. Интеграция обычно содержит настройки, сопоставления полей, расписания и нередко доработки схемы CommerceML под конкретный бизнес. Без описания любое изменение рискует сломать обмен, а разбираться придётся с нуля.
Документ по интеграции с 1С должен отвечать на вопросы:
- Что передаётся. Каталог, цены, остатки, заказы — что именно и в каком направлении.
- Как настроен обмен. Где настройки, по какому расписанию, через какие механизмы.
- Сопоставление полей. Как свойства товаров и данные связаны между 1С и сайтом.
- Что делать при сбое. Типовые проблемы обмена и порядок их диагностики.
Порядок в интеграции — отдельная задача, которую мы закрываем услугами автоматизации на 1С и автоматизации продаж и склада. Хорошо описанный обмен экономит недели при любой передаче проекта.
Процесс разработки и деплой
Часто забываемая, но важная часть документации — как проект собирается и выкатывается. Без этого новый разработчик боится трогать код: непонятно, как безопасно провести изменение на боевой сервер, не сломав работающий магазин.
Что описывают:
- Репозиторий и ветки. Где код, как организованы ветки, как принимаются изменения.
- Процесс деплоя. Как изменение попадает на боевой сервер — вручную или через автоматизацию.
- Тестовое окружение. Есть ли стенд для проверки, как он связан с боевым.
- Откат. Что делать, если выкатили и что-то сломалось.
Идеально, когда процесс не описан на бумаге, а автоматизирован и потому самодокументируем. Настроенный конвейер снимает зависимость от знаний одного человека — об этом наш разбор CI/CD и деплоя на 1С-Битрикс.
Инфраструктура и окружение
Чтобы поддерживать и развивать проект, новая команда должна понимать, на чём он работает. Документация окружения описывает технический фундамент сайта.
- Конфигурация сервера. Версии PHP, веб-сервера, базы данных, особенности настройки.
- Окружение 1С-Битрикс. Используется ли BitrixVM, как настроено, какие модули включены.
- Кэш и производительность. Как настроено кэширование, композитный сайт, что критично для скорости.
- Резервное копирование. Как и куда делаются бэкапы, как восстанавливаться.
Детали серверного окружения на примере типовой инфраструктуры мы разбираем в статье про хостинг и инфраструктуру BitrixVM.
Инструкции для контент-менеджеров
Не вся документация техническая. Часть предназначена людям, которые ежедневно работают с сайтом: наполняют каталог, обрабатывают заказы, ведут контент. Без инструкций эти операции тоже становятся зависимостью от подрядчика.
- Работа с каталогом. Как добавить товар, свойство, торговое предложение, категорию.
- Обработка заказов. Статусы, действия с заказом, что означает каждый этап.
- Управление контентом. Как редактировать страницы, баннеры, меню, акции.
- Типовые проблемы. Что делать, если товар не отображается, не прошёл обмен, не считается скидка.
Такие инструкции снимают с подрядчика поток мелких вопросов и делают бизнес самостоятельным в повседневных операциях.
Что документировать не нужно
Документация должна быть полезной, а не толстой. Избыточные описания устаревают, никто их не читает, и они создают ложное ощущение порядка. Не тратьте ресурс на то, что и так известно или легко находится.
- Типовое поведение 1С-Битрикс. Стандартная работа платформы описана в официальной документации — дублировать её бессмысленно.
- Очевидный код. Понятный, аккуратно написанный код документирует себя сам, комментировать каждую строку не нужно.
- Сиюминутные детали. То, что меняется каждую неделю, устаревает быстрее, чем пишется.
Правило простое: документируйте то, что специфично для вашего проекта и чего нельзя узнать из общедоступных источников. Всё остальное — шум.
Как закрепить документацию в договоре
Документация, оставленная на потом, не пишется никогда: проект сдан, команда переключилась, желание пропало. Поэтому её нельзя ждать как добрую волю — требование закрепляют в договоре как часть результата.
- Включите в состав сдачи. Документация — часть приёмки этапа, а не бонус после завершения.
- Опишите состав. Зафиксируйте, какие документы и доступы передаются: архитектура, обмен, деплой, инструкции.
- Привяжите к оплате. Финальный платёж или приёмка этапа зависит от передачи документации и доступов.
- Проверьте передачу. Не «получили папку», а убедились, что по документам действительно можно работать.
Такой подход превращает документацию из благих намерений в обязательный результат, который бизнес реально получает.
Частые ошибки заказчика
- Доступы на подрядчика. Домен, хостинг, лицензия оформлены на исполнителя, и бизнес теряет контроль.
- Документацию не требуют. Надеются получить её «потом», и не получают никогда.
- Нет описания обмена с 1С. Самая хрупкая часть проекта живёт только в голове одного разработчика.
- Игнорируют процесс деплоя. Новый подрядчик боится трогать код, потому что не знает, как безопасно выкатить.
- Избыточная документация. Тонны неактуальных описаний вместо понятной карты нестандартных решений.
- Документация не в договоре. Требование не закреплено, и его нечем подкрепить при сдаче.
- Не проверяют передачу. Получают папку, но не убеждаются, что по ней реально можно работать.
Чек-лист передачи проекта
- Доступы переоформлены. Домен, хостинг, лицензия, репозиторий, платёжные системы — на заказчика.
- Архитектура описана. Есть понятная карта инфоблоков, компонентов и интеграций.
- Кастомизации задокументированы. Модули, доработки и бизнес-логика описаны и объяснены.
- Обмен с 1С описан. Что передаётся, как настроено, что делать при сбое.
- Процесс деплоя зафиксирован. Репозиторий, ветки, выкатка и откат понятны.
- Окружение описано. Конфигурация сервера, кэш, бэкапы.
- Есть инструкции для персонала. Каталог, заказы, контент, типовые проблемы.
- Передача проверена. Убедились, что по документам и доступам можно реально работать.
Вывод
Документация проекта — это не бюрократия, а страховка независимости бизнеса. Пока подрядчик рядом, она кажется лишней, но именно в кризис — при смене команды, уходе специалиста или срочном инциденте — она определяет, останетесь вы хозяином своего проекта или заложником чужих знаний.
Начните с главного: переоформите на себя все доступы и лицензии. Затем добейтесь описания нестандартного — кастомизаций, обмена с 1С, процесса деплоя, — не тратя ресурс на типовое поведение Битрикса. И закрепите требование в договоре как часть сдачи, потому что документация, оставленная на потом, не появляется никогда. Собранная вовремя, она стоит недель работы при любой передаче проекта.
