Writing technical documentation for 1C-Bitrix

Writing Technical Documentation for 1C-Bitrix

A developer leaves, and the next one spends three weeks figuring out how a non-standard 1C synchronization component works. A Bitrix core update breaks a custom module because no one recorded which hooks it uses. Without documentation there is no transferability: every team starts from scratch. On Bitrix projects the situation is compounded by a mix of the legacy core, the D7 API, and custom modules — without a description it is unclear even where things are located.

What We Document on a Bitrix Project

Project architecture:

• Directory structure: what lives in /local/, which custom modules are in /local/modules/, where site templates are located
• Editions and versions in use: Bitrix, PHP, DBMS, OS
• Server infrastructure diagram (if more than one machine)
• Third-party library list (Composer, npm)

Modules and components: For each custom module: purpose, list of public methods, event hooks used, dependencies on other modules, database tables.

Integrations: For each external integration: which system, mechanism (API, CommerceML, webhooks), connection parameters (where keys are stored), schedule, what to do on failure.

Deployment and maintenance: Step-by-step instructions for deploying on a clean server, the Bitrix core update procedure, rollback procedure.

Code Documentation Standards

For PHP — PHPDoc blocks on all public methods:

/**
 * Resolves an article number to a trade offer ID.
 *
 * @param  string $article  Product article number (PROPERTY_CML2_ARTICLE)
 * @param  int    $iblockId Information block ID for trade offers
 * @return int|null         Offer ID, or null if not found
 *
 * @throws \Bitrix\Main\ArgumentException On invalid iblockId
 */
public function resolveArticle(string $article, int $iblockId): ?int

For non-standard solutions — inline comments explaining "why", not "what":

// Using SELECT FOR UPDATE here instead of ORM because
// DataManager does not support locking reads in the current version of Bitrix

Documentation Format

README.md — the first file a new developer opens. Structure:

1. What the project is and what problems it solves
2. Requirements (PHP, extensions, DBMS)
3. Installation in 5 steps
4. Project structure
5. Links to detailed documentation

API documentation — if the project exposes a REST API, document it in OpenAPI 3.0 format (openapi.yaml). For internal Bitrix AJAX controllers, a table of endpoints with parameters and response examples is sufficient.

Administrator guide — for editors and managers: how to add a product, configure a promotion, view orders. Screenshots of the Bitrix admin panel with annotations.

Tooling and Storage

Documentation is stored alongside code — in the Git repository, in a /docs/ directory. This ensures versioning and accessibility for the entire team. For heavyweight guides with images — Confluence or Notion with repository synchronization.

Staying up to date is the biggest documentation challenge. Solution: documentation as part of the Definition of Done — a task is not closed until the corresponding documentation page has been updated.

What Is Included in Writing Documentation

• Audit of existing documentation and identification of gaps
• Writing the architectural description of the project (structure, modules, integrations)
• Documenting custom modules and non-standard components
• Describing all integrations with parameters and recovery procedures
• Deployment and maintenance instructions
• User guide for the admin panel