Writing a Technical Specification for a 1C-Bitrix Website
A project without a specification is a project whose specification is written after the fact in chat messages. The developer remembers one thing, the client expected another, and the eventual dispute over "what was in scope" consumes budget and goodwill. The specifics of 1C-Bitrix make the problem worse: the platform has its own architecture (iblocks, components, modules, 1C sync), and if the specification says "product catalog with filtering" without specifying property types and the facet index, the developer will implement the minimum viable option — and the client will get a filter that takes 8 seconds on 20,000 SKUs.
Structure of a Specification for a Bitrix Project
A Bitrix project specification is not the same as a specification for an arbitrary website. In addition to standard sections (goals, audience, functional requirements), Bitrix-specific sections are required.
Section: Edition and Licensing
Specifies the Bitrix edition ("Start", "Standard", "Small Business", "Business", "Enterprise") with justification. For an online store, the minimum is "Small Business" (the catalog module, trade offers, 1 price list). If an extended catalog with multiple price types, rule-based discounts (sale.discount), and multi-warehouse stock aggregation is needed — "Business" or "Enterprise".
Section: iblock Structure
Lists all iblocks with their property types. This is where the decision is made that cannot be painlessly changed later: property type "String" vs "Reference" (HL-block). For each iblock — a table:
| Property | Type | Multiple | Used in filter |
|---|---|---|---|
| Brand | Reference (HL) | No | Yes |
| Color | List | Yes | Yes |
| Description | HTML/Text | No | No |
Section: Integrations
The 1C sync is described separately: sync direction (bidirectional or 1C export only), frequency, what is synchronized (stock, prices, images, properties). Writing simply "1C integration" is a mistake. What is needed: which 1C configuration, standard CommerceML exchange or a custom API integration, field mapping.
Section: Performance
SLA for page response times: catalog section ≤ N seconds with M concurrent users. This is the only way to formalize performance requirements — without this section, performance complaints cannot be formally raised.
Designing User Scenarios
A specification without user scenarios describes a system but not how people use it. For Bitrix projects, scenarios are especially important for:
- Checkout flow: number of steps, whether authentication is required, delivery/payment methods, cart behavior for unauthenticated users
- Personal account: order history from
b_sale_order, statuses, ability to reorder - Admin scenario: how a manager adds a product, edits a price, processes an order
Each scenario is described as a sequence of steps with references to the Bitrix components involved, or marked "custom development."
What Is Often Missed
User roles and permissions. Bitrix has user groups and a permission system for iblocks, sections, and components. If the site has a B2B portal or dealer section — the group structure and access matrix must be specified in the requirements.
Technical SEO requirements. Human-readable URLs (SEF URLs), meta tag format, robots.txt, sitemap.xml — all configured in Bitrix via the seo module and component parameters. Without explicit requirements, the developer will use defaults.
Multilingual support. If the site is planned for multiple languages — the specification must describe the structure of language sites within a single Bitrix core, content mapping, and locales for dates and currencies.
Case Study: How the Absence of a Spec Cost Three Months of Work
Client — a wholesale supplier who wanted "a catalog with filtering and a dealer personal account." A 2-page specification written internally by the client team. After launch it turned out:
- Dealers needed individual prices (three price types by group), but the developer implemented a single price list
- The filter did not account for warehouse stock — out-of-stock products appeared in results
- The personal account showed only orders placed through the website, while dealers expected their full history from 1C
The rework took 3 months against an original development budget of 6 weeks. Had these requirements been formalized before development began, the scope and cost would have been estimated correctly.
What Writing the Specification Includes
- Client interviews: business processes, users, integrations
- Analysis of existing systems (1C, CRM, warehouse)
- Designing the iblock and property structure
- Describing user scenarios for all roles
- Functional requirements mapped to Bitrix components and modules
- Non-functional requirements: performance, security, scalability
- Wireframing key screens
- Review and finalization of the document
A typical online store specification runs 40–80 pages. Preparation time: from 2 weeks for a small project to 6–8 weeks for a complex multi-functional portal with multiple integrations.