Creating an Administrator's Guide for 1C-Bitrix
An administrator's guide for a Bitrix project is not a retelling of the official 1C-Bitrix documentation. It is a description of a specific installation: which infoblocks exist and what can be edited in them, how the publication workflow works, which settings must not be touched and why. Without such documentation, each new administrator spends weeks learning the system, and half of all questions are resolved with a call to the developer.
What should be in the guide: document structure
A typical structure for a Bitrix website administrator guide:
Section 1: Access and Environment. Addresses of admin panels, test and production servers. Credentials — not in the document, but a link to a password manager. Description of roles: who is the main administrator, who is the content manager, what permissions each group has. User groups in Bitrix are configured in /bitrix/admin/groups.php, module permissions — in the same place.
Section 2: Content Management. This comprises 40-50% of the document volume. For each infoblock: name, location in the admin menu, which fields are mandatory and which are optional, restrictions (maximum image size, allowed file formats). Screenshots for each non-standard field.
Section 3: Catalog Management (for e-commerce). Adding products, managing prices through the catalog module, working with inventory (b_catalog_store_product), managing discounts and coupons in the sale module.
Section 4: Orders and Customers. Order lifecycle: statuses in /bitrix/admin/sale_order.php, when and how to change statuses, what happens at each transition (emails sent, bonuses deducted).
Section 5: Technical Procedures. Backup, kernel update, cache clearing. The administrator should understand these even without a developer.
Describing infoblocks: template for each
Create a card for each infoblock using this template:
Infoblock: News
Type: news | ID: 3 | Symbolic Code: news
Location in Menu: Content → News
Admin List URL: /bitrix/admin/iblock_list_admin.php?IBLOCK_ID=3&type=news
Element Fields:
- Title (NAME) — mandatory. News headline
- Symbolic Code (CODE) — generated automatically, do not edit
- Publication Date (ACTIVE_FROM) — if not specified, news publishes immediately
- Preview (PREVIEW_TEXT) — brief description for list, up to 300 characters
- Preview Image (PREVIEW_PICTURE) — 800×600 px, JPG/PNG, maximum 500 KB
- Detail Text (DETAIL_TEXT) — TinyMCE editor, full news text
- Tags (TAGS) — comma-separated, used for filtering
What not to do:
- Change the symbolic code of a published news item (breaks URL and loses search rankings)
- Delete sections with active elements without reassignment
This format is understandable to people without technical background and does not require explanations at each inquiry.
Describing technical procedures
Cache clearing
The most frequent action after changes that "don't show" on the site. Cache is cleared in /bitrix/admin/cache.php. Two options there: clear all cache or only the cache of a specific component. In the guide, describe what exactly to clear in different situations — full site cache is rarely needed, usually component cache is sufficient.
If the site uses HTML cache (/bitrix/html_pages/), it needs to be cleared separately. In the guide — separate instructions with path and screenshot.
Backup
Bitrix has a built-in backup module (/bitrix/admin/backup.php). For the guide describe: how to create a manual backup, where it is stored, how long the automatic copy is kept, and most importantly — how to restore the site from a backup. This step is usually not documented, but it's needed in a critical moment.
Module updates
Updates in Bitrix are installed through "Marketplace" or through /bitrix/admin/update_system.php. In the guide: when to update (not immediately after release — give time for bugs to surface), how to verify functionality after update (list of pages to check), who to contact if problems arise.
Keeping the guide current
The guide becomes outdated with each site update. Establish a process: when delivering a task, the developer updates the corresponding section of the guide. Use a system with version history for storage — Confluence, Notion, or even Google Docs with change history. A Word file on a server is an anti-pattern.
Do not put the guide in the project's Git repository — it contains operational information not related to code and often includes sensitive infrastructure details.
Specifics for multi-site installations
If several sites run on one Bitrix kernel, the guide must clearly distinguish: which infoblocks are shared, which are site-specific. The b_iblock table contains the SITE_ID field, by which the infoblock is attached. The administrator must understand that changing a "shared" infoblock will affect all sites in the installation.