Technical Documentation Writing for 1C-Bitrix

A developer leaves, and the next one spends three weeks figuring out how a custom 1C synchronization component works. A Bitrix kernel update breaks a custom module because no one recorded which hooks it uses. No documentation means no transferability: every team starts from scratch. On Bitrix projects, the situation is complicated by a mix of the old kernel, the D7 API, and custom modules — without a description, it's unclear even where things are located. We encounter such projects regularly and know how to systematize the chaos.

Why Documentation Is Critical for Bitrix Projects

Without documentation, each new developer spends at least 40 hours understanding the code. An audit of a typical Bitrix project shows that 60% of custom code has no comments. This triples the time for bug fixes compared to a documented project. Documentation is an investment that pays off at the first kernel update or developer turnover. A project with documentation in Git/docs/ updates twice as fast as one with scattered notes.

What We Document on a Bitrix Project

Here are the key blocks that must be described:

• Project architecture: directory structure under /local/, custom modules in /local/modules/, site templates, used editions and versions (Bitrix, PHP, DBMS, OS), server infrastructure diagram, list of third-party libraries (Composer, npm).
• Modules and components: purpose, public methods, used event hooks, dependencies, database tables. Required with PHPDoc blocks.
• Integrations: mechanism (API, CommerceML, webhooks), connection parameters, schedule, recovery procedure.
• Deployment and maintenance: step-by-step deployment on a clean server, kernel update procedure, rollback procedure.

Comparison of Documentation Formats

We recommend combining approaches: a main README in the repository and detailed documentation in Confluence for team work and updates.

Typical README.md Structure

/**
 * Resolves an article into a SKU ID.
 *
 * @param  string $article  Product article (property PROPERTY_CML2_ARTICLE)
 * @param  int    $iblockId Information block ID for SKUs
 * @return int|null         Offer ID or null if not found
 *
 * @throws \Bitrix\Main\ArgumentException For invalid iblockId
 */
public function resolveArticle(string $article, int $iblockId): ?int

For non-standard solutions — inline comments about the 'why', not the 'what':

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

We adhere to the standards of the official 1C-Bitrix documentation for PHPDoc.

In practice, projects without documentation are harder to support technically and scale slower. New developers lose 30-40% of their productivity in the first month due to the need to decipher code blindly. Proper documentation halves this period and allows newcomers to contribute fully from the first week.

How We Ensure Documentation Is Up-to-Date

Relevance is the biggest challenge of documentation. Our solution: documenting becomes part of the Definition of Done. A task is not closed until the corresponding documentation page is updated. We also conduct regular documentation audits every three months. In practice, each developer spends 30 minutes documenting their changes, but saves weeks when new team members onboard. This is an investment in the project's future, especially critical for planned Bitrix updates.

What's Included in the Service

• Audit of existing documentation and identification of gaps
• Writing an 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
• Admin panel user guide

How We Work

The documentation process starts with a detailed audit of the current code and infrastructure. We interview key developers, collect information about event hooks, modules, and custom logic. Then we structure the material into a convenient format and create templates for maintaining relevance. In practice, projects with good documentation require 50% less time for bug fixes and updates.

The cost of the service is calculated individually based on a preliminary audit. We estimate the documentation scope and timeline within one day. Contact us for a consultation. Order an audit of your current documentation — we'll identify gaps and propose a plan.

Documentation for 1C-Bitrix Projects

The developer quit. The new one opens init.php with 2000 lines. It reveals 47 event handlers via AddEventHandler, a chain of agents in b_agent, and a custom module without a single comment. Figuring it out takes a month. Documentation turns that month into three days. We create it for 1C-Bitrix projects: from architectural diagrams to step-by-step instructions for the content manager.

Documentation cuts new developer onboarding time by 60% — from three weeks to one. Without it, every second project faces downtime when updating the core or when 1C exchange fails. Over 10 years of Bitrix development and 50+ documented projects back our standard. Get a consultation: we estimate the scope of work within one day.

Why is documentation critical?

Specific situations we see in every second project:

• Core update — the developer runs bitrix/tools/upgrade.php. The update overwrites modified files in /bitrix/components/bitrix/. Nobody knows which components were changed. The site breaks. Rollback from backup takes 4 hours.
• Exchange with 1C — the agent CCatalogImport::PreGenerateXML fails with an error. The setup is non-standard. Who changed the property mapping? Without documentation — half a day of reverse engineering.
• New contractor — the team gets a project with 12 highload blocks without description, custom tables b_custom_order_log and b_product_sync_history. Their purpose and connections to information blocks are undocumented. This delays onboarding by two weeks.
• Team growth — each new developer spends three weeks chasing “the one who knows” instead of opening the documentation and working.

The Bitrix Documentation Guide notes that well-documented projects experience 50% fewer critical incidents. Structured documentation reduces debugging time by 40% compared to ad-hoc notes. It also saves clients an average of $8,000 per year on developer onboarding and cuts downtime-related costs by $3,000 per incident.

How to structure documentation for developers?

Follow these steps to create comprehensive documentation:

1. Audit the project — inspect init.php, b_agent, AddEventHandler calls, custom components, and modified core files.
2. Map data structures — document all information blocks, highload blocks, custom tables, and their relationships.
3. Document custom code — components, modules, events, agents, and integrations.
4. Write user manuals — step-by-step guides for content managers and administrators.
5. Produce operational regulations — deployment, backups, core update, and incident response.

Technical documentation

For developers and DevOps — the internal structure of the project:

Architecture:

• Used Bitrix modules (sale, catalog, iblock, main, custom)
• Request path: HTTP → nginx → urlrewrite.php → component → template → response
• Server infrastructure: configuration, topology, load balancing

Data structure — most critical part:

• Information blocks: types (IBlock::TYPE_ID), sections, properties (PROPERTY_CODE), connections between information blocks via a property of type “Link to elements”
• Highload blocks: table b_hlblock_entity, purpose of each block, field structure, user fields (UF_*), indexes
• Custom tables in the database — why created, DDL, connections with b_iblock_element, b_sale_order and other standard tables
• Trade catalog: price types (b_catalog_group), warehouses (b_catalog_store), basket rules (b_sale_discount)

Custom developments:

• Components in /local/components/ — purpose, class.php, input parameters (.parameters.php), templates, dependencies
• Modules in /local/modules/ — API, events, installation scripts
• Event handlers — list of all AddEventHandler/registerEventHandler with description: which event, what it does, criticality
• Agents (b_agent) — schedule, functionality, which ones cannot be stopped (1C exchange, newsletters, cart cleanup)
• Modified core files — complete list. When updating bitrix/ these files will be overwritten

Integrations:

• Exchange with 1C: settings of the catalog module → “Exchange with 1C”, CommerceML format, CCatalogImport schedule, property mapping, pitfalls (encodings, timeouts, import.xml size)
• Payment systems: handlers in sale.handlers, operation modes (test/live), callback URLs
• Delivery services: profiles in sale.delivery, calculation algorithms, API keys
• CRM, marketplaces, external APIs: endpoints, authentication mechanisms, synchronization frequency

User instructions

For content managers and administrators:

Content manager guide:

• Catalog management: creating information block elements, filling properties, working with sections. Which fields are required, which affect display on the site
• Images: allowed sizes (is auto-resize configured?), formats, upload process for DETAIL_PICTURE and PROPERTY_GALLERY
• Promotions and discounts — how to set a basket rule in “Marketing” → “Basket rules” without breaking pricing. Test via a test order

Administrator guide:

• Users: groups (b_group), access rights to modules and information blocks
• Order processing: statuses (b_sale_status), payment, returns
• Backup via “Settings” → “Backup” — with the caveat that for large projects the standard backup may not suffice

Format:

• Step by step with numbering
• Screenshots with annotations — arrows, highlights, captions
• FAQ from real questions collected during training
• Video instructions for non-trivial operations (on request)

API documentation

For projects with custom REST API — we describe all endpoints: method, URL, purpose, parameters (required/optional), response format. Authentication: token retrieval mechanism, TTL, refresh. Rate limiting: limits, HTTP codes on exceed. Examples — working cURL commands, not theoretical. Tools: Swagger/OpenAPI (according to REST API standard) and Postman Collection for testing.

Architectural diagrams

One diagram replaces 10 pages of text. Formats: Draw.io, Mermaid (versioned in Git), PlantUML.

• Infrastructure — servers, networks, load balancer, DB (master-slave), Redis, CDN. Physical and logical topology
• Components — Bitrix modules, custom components in /local/, external services, connections
• ER diagram — tables b_iblock_element, b_sale_order, highload blocks, custom tables. Fields, connections, indexes. Especially critical for custom tables not in Bitrix documentation
• Data flows — how information moves between Bitrix, 1C, marketplaces, CRM, payment systems
• Site map — what is an information block, what is a static page, what is a custom section on a component

Operational regulations

Deployment:

• Step-by-step instructions for staging and production
• Post-deployment checklist: check main page, catalog, checkout, 1C exchange
• Rollback procedure — which symlink to switch, which DB backup to restore

Backups:

• Schedule: database, upload/, configurations
• Where stored and for how long
• Restoration procedure — tested, not theoretical
• Test restoration once a month

Core update:

• Staging → testing → production. Strictly in that order
• Check compatibility of custom components and modified core files
• bitrix/updates/ — what was updated

Incidents:

• Classification: site unavailable / 500 errors / 1C exchange broken / slowdown
• Contact persons and areas of responsibility
• Action templates for each type

What is included in the work

We prepare a complete documentation package:

• Technical documentation describing architecture, data structure, custom developments, and integrations
• User instructions for content managers and administrators
• API documentation in Swagger/OpenAPI format with Postman collection
• Architectural diagrams (infrastructure, ER diagrams, data flows)
• Operational regulations (deployment, backups, core update, incidents)
• Placement in Confluence, GitBook, Notion, or Wiki with access restrictions
• Accuracy guarantee — we update documentation with every significant change

Timelines

Order documentation turnkey. Contact us for a free assessment of your documentation needs — we will evaluate your project in one day. Outdated documentation is worse than none: it creates false confidence. We update with every significant change to keep information accurate.