Написання технічної документації для 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С-Бітрікс для проєктів будь-якої складності: від архітектурних схем до покрокових інструкцій для контент-менеджера.

Наявність документації скорочує час адаптації нового розробника втричі — з трьох тижнів до одного. Проєкт без неї вимагає в 3 рази більше часу на введення новачка; даунтайми при оновленні ядра трапляються на 60% частіше. Понад 10 років досвіду розробки на Бітрікс і 50+ задокументованих проєктів — це наш стандарт. Економія на онбордингу одного розробника може сягати 90 000 грн — саме стільки коштує місяць простою без документації. Зв’яжіться з нами для оцінки вашого проєкту за один день.

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

Конкретні ситуації, які бачимо на кожному другому проєкті:

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

Статистика наших проєктів: при наявності повної документації кількість інцидентів при оновленні модулів знижується на 50%, а середній час виправлення помилки в продакшні скорочується вдвічі.

Один із кейсів — інтернет-магазин з 500 000 товарів, обмін з 1С, три платіжні системи, інтеграція з СДЕК. Без документації новий розробник розбирався 4 тижні. Ми задокументували архітектуру даних (інфоблоки, HR-блоки, кастомні таблиці), REST API, регламенти деплою та бекапів. Після цього введення новачка зайняло 1 тиждень, а вартість підтримки зменшилася на 35% за рахунок зниження часу на налагодження. За стандартом CommerceML (описано у Вікіпедії) обмін з 1С — одна з найчастіших точок збою. Документація знімає цю проблему.

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

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

Для розробників і 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 та 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С / гальмує
• Контактні особи та зони відповідальності
• Шаблони дій для кожного типу

Як відбувається створення документації?

1. Аналіз проєкту (1–2 дні) — вивчаємо код, БД, конфігурації, спілкуємося з командою.
2. Збір інформації (2–5 днів) — фіксуємо архітектуру, інтеграції, бізнес-процеси.
3. Написання та валідація — формуємо технічну документацію, інструкції, схеми. Кожен текст перевіряє розробник, який брав участь у проєкті.
4. Розміщення — Confluence, GitBook, Notion або Wiki з розмежуванням доступу.
5. Гарантія актуальності — оновлюємо документацію при кожній значущій зміні (новий модуль, зміна обміну, оновлення ядра).

Створення документації 1С-Бітрікс за цим алгоритмом забезпечує точність і повноту — жоден кастомний агент або змінений файл ядра не залишиться незадокументованим. Замовте попередню оцінку документації — ми проаналізуємо ваш проєкт і назвемо строки та обсяг робіт.

Що входить в роботу

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

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

Джерело: власна методологія, апробована на 50+ проєктах на 1С-Бітрікс.

Строки

Замовте документацію під ключ — зв’яжіться з нами для безкоштовної оцінки вашого проєкту за 1 день. Застаріла документація гірша за її відсутність: вона створює хибну впевненість. Ми оновлюємо матеріали при кожній суттєвій зміні, щоб інформація залишалася точною. Отримайте консультацію прямо зараз.