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
| Format | Advantages | Disadvantages |
|---|---|---|
| README.md in repository | Versioning, accessibility, easy to edit | Limited formatting, not suitable for large volume |
| Confluence / Notion | Rich formatting, screenshots, search, team collaboration | Requires synchronization with code, cloud dependency |
| OpenAPI 3.0 | Automatic client generation, industry standard | Complexity for internal APIs and non-standard solutions |
We recommend combining approaches: a main README in the repository and detailed documentation in Confluence for team work and updates.
Typical README.md Structure
| Section | Content |
|---|---|
| Description | Brief project overview, problems solved |
| Requirements | PHP, extensions, DBMS, versions (details in Bitrix documentation) |
| Installation | Step-by-step instructions |
| Project Structure | Links to subdirectories and modules |
| References | Detailed documentation and contacts |
Example PHPDoc for a Custom Module
/** * 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.