Написання технічної документації для 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: завдання не закрите, поки не оновлена відповідна сторінка документації.
Що входить до написання документації
- Аудит наявної документації та виявлення прогалин
- Написання архітектурного опису проєкту (структура, модулі, інтеграції)
- Документування кастомних модулів та нестандартних компонентів
- Опис усіх інтеграцій з параметрами та процедурами відновлення
- Інструкції з розгортання та обслуговування
- Посібник користувача адміністративного розділу