Проект сдан, сайт работает, все довольны. А через полгода подрядчик занят, у вас появляется новая задача — и выясняется, что никто в компании не знает, где лежат доступы, как устроен обмен с 1С и почему при определённых условиях цена в каталоге отличается от учётной. Знания о проекте оказались в голове одного человека, к которому теперь не дотянуться. Это не редкость, а типичный финал проекта без документации.
Документация — это не бюрократия ради галочки, а страховка бизнеса от потери контроля над собственным сайтом. В этой статье разберём, что именно нужно требовать и передавать после разработки на 1С-Битрикс: доступы, архитектуру, регламент обмена с 1С, инструкции по деплою и поддержке. И как закрепить это так, чтобы документация не осталась «на словах». Тему мы знаем изнутри — принимаем чужие проекты в поддержку и часто проводим аудит и оптимизацию на 1С именно там, где документации не оставили.
Коротко
- Документация снимает зависимость от одного подрядчика и делает проект управляемым — это бизнес-страховка, а не формальность.
- Минимальный пакет: доступы, архитектура, регламент обмена с 1С, деплой, инструкция для контент-менеджера.
- Состав и формат документации фиксируют заранее в договоре или ТЗ, а не «выясняют» на сдаче.
- Документацию нужно поддерживать живой — устаревшая инструкция иногда опаснее её отсутствия.
Зачем нужна документация
Документация отвечает на простой вопрос: что делать бизнесу, когда конкретного разработчика рядом нет. А его рано или поздно не будет — сменится подрядчик, уйдёт сотрудник, закончится договор. Документация переводит знания о проекте из чьей-то головы в актив компании, которым можно распоряжаться.
Конкретно она даёт бизнесу три вещи:
- Независимость. Любой квалифицированный подрядчик сможет разобраться в проекте по документам, а не через дорогой реверс-инжиниринг.
- Скорость. Новые задачи решаются быстрее, потому что не нужно каждый раз заново изучать «как тут всё устроено».
- Управляемость рисками. При сбое понятно, где искать причину и к кому обращаться, а не «всё сломалось, и мы не знаем почему».
Что происходит без неё
Чтобы ценность документации была нагляднее, посмотрим на типичные последствия её отсутствия.
| Ситуация | С документацией | Без документации |
|---|---|---|
| Смена подрядчика | Передача за дни | Дорогой аудит с нуля |
| Сбой обмена с 1С | Есть регламент действий | Долгий разбор «вслепую» |
| Доступ к серверу | Хранится и известен | Ищут по перепискам |
| Доработка функции | Понятна архитектура | Риск сломать смежное |
| Уход сотрудника | Знания в документах | Знания ушли вместе с ним |
Каждая строка — это деньги и время. Отсутствие документации не бесплатно: оно оплачивается позже, обычно в неудобный момент и по более высокой ставке. Аудит запущенного проекта стоит дороже, чем аккуратная передача при сдаче.
Доступы и учётные данные
Самое базовое и самое часто теряемое — доступы. Без них проект физически неуправляем. Полный реестр доступов должен быть передан и храниться в безопасном месте (менеджер паролей), а не в переписке.
- Хостинг и сервер. Доступ к панели, SSH, конфигурации BitrixVM или иного окружения.
- Админка Битрикс. Учётная запись администратора с полными правами.
- Домен и DNS. Регистратор, панель управления зоной, SSL-сертификаты.
- Репозиторий. Доступ к Git с историей проекта.
- 1С и обмен. Учётные данные интеграции, ключи API, реквизиты подключения.
- Внешние сервисы. Платёжные системы, службы доставки, аналитика, почта, SMS.
Архитектура и структура проекта
Доступы дают вход, а карта архитектуры — понимание, что внутри. Этот раздел объясняет новому специалисту устройство проекта без чтения всего кода подряд.
- Редакция и версия. Какая редакция 1С-Битрикс используется, ключевые модули.
- Инфоблоки и каталог. Структура инфоблоков, торгового каталога, свойств и их назначение.
- Нестандартная логика. Всё, что сделано не «из коробки»: кастомные компоненты, события, агенты, обработчики.
- Кэширование. Как настроен композитный сайт и кэш, что и как инвалидируется.
- Интеграции. Список внешних систем и точек их подключения.
Особенно важно описать нестандартные решения — именно они ломаются непредсказуемо и именно их сложнее всего разобрать по коду. Если проект включает собственные модули, к ним прикладывают отдельное описание. Как грамотно оформлять такую разработку, мы разбираем в статье про разработку модуля для Битрикс, а более сложные случаи маркетплейс-решений — в материале про разработку модуля для Маркетплейса Битрикс.
Регламент обмена с 1С
Обмен с 1С — самая частая точка отказа в проектах на Битрикс, поэтому его документируют тщательнее всего. Когда «поехали цены» или «пропали остатки», без регламента разбор занимает часы, а с ним — минуты.
Регламент обмена описывает:
- Что передаётся. Товары, цены, остатки, заказы, статусы — перечень сущностей и направление обмена.
- Как передаётся. Механизм (CommerceML, REST, промежуточный сервис), формат, расписание.
- Ключи сопоставления. По каким кодам (XML_ID, код 1С, артикул) товары и заказы связываются между системами.
- Правила и исключения. Как обрабатываются цены по группам, кратность, несколько складов, нестандартные свойства.
- Действия при сбое. Как диагностировать, где логи, что делать и к кому обращаться.
Обмен часто строится на REST и вебхуках, и здесь документация смыкается с безопасностью: где хранятся ключи, как защищён канал, что делать при их компрометации. Эту сторону мы подробно разбираем в статье про REST, вебхуки и безопасность в Битрикс. Настройку самого обмена закрываем услугой автоматизации продаж и склада на 1С.
Код, репозиторий и деплой
Если по договору код принадлежит заказчику, передают не архив файлов с боевого сервера, а полноценный репозиторий Git с историей. История коммитов — это тоже документация: по ней видно, что и зачем менялось.
- Репозиторий. Доступ к Git со всей историей и понятной структурой веток.
- Сборка. Как собрать проект, какие зависимости и версии нужны.
- Окружения. Чем боевое отличается от тестового, какие настройки где лежат.
- Деплой. Как выкатывать изменения без риска уронить продакшн.
Инструкция по деплою критична: без неё даже простое обновление превращается в риск. В зрелых проектах выкладка автоматизирована через CI/CD, и этот процесс тоже документируют. Как выстроить надёжный деплой на Битрикс, мы разбираем в отдельной статье про CI/CD и деплой Битрикс. Устройство инфраструктуры, на которой всё работает, — в материале про хостинг и инфраструктуру BitrixVM.
Инструкции для контент-менеджера
Техническая документация нужна разработчикам, а бизнесу ежедневно работает контент-менеджер. Ему нужны простые пошаговые инструкции по типовым операциям, а не описание архитектуры.
- Товары и каталог. Как добавить товар, свойства, цены, изображения, привязать к разделу.
- Контент. Как редактировать страницы, статьи, баннеры, меню.
- Заказы. Как найти и обработать заказ, сменить статус, что при этом происходит в 1С.
- Типовые ситуации. Что делать, если товар не отобразился, цена не та, изображение не встало.
Хорошая инструкция для контент-менеджера окупается сразу: она снимает поток мелких вопросов к подрядчику и делает команду заказчика самостоятельной в рутине. Это дешёвая документация с быстрым эффектом.
Регламент поддержки и SLA
Отдельно от технических документов фиксируют правила сопровождения — кто, что и в какие сроки делает после сдачи.
- Каналы обращения. Куда писать по инцидентам и задачам, как ставить заявки.
- Сроки реакции. SLA на критичные сбои и на плановые задачи — разные приоритеты.
- Зоны ответственности. Что покрывает поддержка, что оплачивается отдельно.
- Резервные копии. Как часто делаются бэкапы, где хранятся, как восстанавливаться.
Регламент поддержки превращает отношения с подрядчиком из «позвоним, если сломается» в предсказуемый процесс. Особенно важен пункт про бэкапы: понимание, что и как восстанавливается, — часть управления рисками, а не мелочь.
Как поддерживать документацию живой
Документация, переданная один раз и забытая, устаревает с первым же изменением. Мёртвая инструкция, которая описывает то, чего уже нет, иногда опаснее её отсутствия — по ней принимают неверные решения.
- Держите её рядом с кодом. Техническую документацию удобно вести в репозитории, чтобы правки шли вместе с изменениями.
- Правьте при изменениях. Существенное изменение сопровождается обновлением документации — как часть задачи, а не «потом».
- Версионируйте. Понятно, какая версия документа к какому состоянию проекта относится.
- Назначьте ответственного. У документации должен быть владелец — обычно это подрядчик на поддержке.
Живая документация — это привычка команды, а не разовый артефакт. Её проще поддерживать, если она изначально лежит там, где ведётся работа, и обновляется тем же процессом, что и код.
Как закрепить в договоре
Чтобы документация не стала предметом спора на сдаче, её состав и формат фиксируют заранее — в договоре или ТЗ. Тогда документирование заложено в смету и сроки, а не «всплывает» в последний день.
- Состав пакета. Перечислите, какие документы входят в поставку.
- Формат и место. В каком виде и где передаётся документация.
- Права на код. Кому принадлежит код и как передаётся репозиторий.
- Принадлежность доступов. Домен, хостинг и сервисы оформлены на заказчика.
- Обновление на поддержке. Обязательство держать документацию актуальной.
Частые ошибки
- Документации нет вовсе. Знания остались в голове разработчика, проект неуправляем без него.
- Доступы на подрядчике. Домен и хостинг оформлены на исполнителя — заказчик заложник.
- Только техдок без инструкций. Разработчику понятно, а контент-менеджер беспомощен.
- Обмен с 1С не описан. Самая частая точка отказа осталась «чёрным ящиком».
- Передали архив вместо репозитория. Нет истории изменений, нет инструкции по сборке и деплою.
- Документация не обновляется. Устарела после первой же доработки и вводит в заблуждение.
- Состав не закреплён в договоре. На сдаче выясняется, что «это не входило».
Чек-лист приёмки документации
- Доступы переданы. Хостинг, админка, домен, репозиторий, 1С, внешние сервисы — всё у заказчика.
- Архитектура описана. Редакция, инфоблоки, нестандартная логика, кэширование, интеграции.
- Регламент обмена с 1С есть. Что, как, по каким ключам, что делать при сбое.
- Код и деплой. Репозиторий с историей, инструкции по сборке и выкладке.
- Инструкции для контента. Пошаговые руководства по типовым операциям.
- Регламент поддержки. Каналы, сроки, зоны ответственности, бэкапы.
- Формат и хранение. Документация структурирована, версионируется, доступна.
- Закреплено в договоре. Состав, права на код и принадлежность доступов зафиксированы.
Вывод
Документация — это не отчётность ради формы, а актив, который определяет, кто на самом деле управляет вашим сайтом. С ней бизнес независим от конкретного исполнителя, быстро решает задачи и предсказуемо реагирует на сбои. Без неё проект держится на памяти одного человека, а любое изменение или смена подрядчика превращается в дорогое расследование.
Минимум обязателен всегда: доступы, архитектура, регламент обмена с 1С, деплой и инструкции для команды. Закрепите состав в договоре на старте, оформите принадлежность доступов на себя и договоритесь поддерживать документацию живой. Это недорогая страховка, которая окупается в первый же момент, когда что-то пойдёт не так, — а этот момент обязательно наступит.
