Creating a user manual for 1C-Bitrix

Writing a User Manual for 1C-Bitrix

Most user manuals for Bitrix projects are written once and become outdated instantly: a screenshot from 2021 shows a menu that no longer exists, and the instruction "click the red button" doesn't work because the button was redesigned as a blue link. A quality user manual is a living document with a clear structure, concrete steps, and an update mechanism.

Audience and Their Tasks

Before writing — define who will be reading and what they need to do. A Bitrix project typically has several groups:

Content manager — adds and edits pages, news, products. Works in the visual editor and admin panel. Doesn't understand PHP or databases. Needs instructions for specific operations with specific buttons.

SEO specialist — configures meta tags, URLs, sitemap. Works in the Bitrix SEO panel and page editor. Needs to know where things are and how changes take effect.

Online store manager — processes orders, manages stock, sets up promotions. Main work is in the "Online Store" module. Needs clear step-by-step workflows for routine tasks.

Developer/administrator — deployment, updates, access rights. Needs technical documentation, not a user manual.

Mixing audiences in a single document is a mistake. It's better to have separate manuals or clearly marked sections "who this section is for".

Manual Structure for Content Manager

An effective structure is built around tasks, not menu items:

1. Logging in and navigation
2. Working with news
   2.1. Add a news item
   2.2. Edit a published news item
   2.3. Schedule publication for a date
   2.4. Unpublish (do not delete!)
3. Working with pages
   3.1. Editing text via the visual editor
   3.2. Adding images (size requirements)
   3.3. Managing page SEO parameters
4. Working with the product catalog
   4.1. Add a product
   4.2. Change price
   4.3. Manually update stock
   4.4. Add a product to a section / remove from a section

Writing Instructions: Specifics Over Description

Bad: "In the content management section, select the required iblock and add an element."

Good:

1. Open Content → Product Catalog in the left menu of the admin panel
2. Click the Add element button in the top right corner
3. Fill in the fields:
   • Name — the full product name (e.g.: "Office chair Comfort Pro, black")
   • Symbolic code — in Latin with hyphens (e.g.: office-chair-comfort-pro-black). Generated automatically, but verify it
   • SKU (field "SKU") — from the supplier's price list
4. Go to the Images tab, upload the main photo (minimum 800×800 px, JPG)
5. Click Save

Each step — one action. Name UI elements in bold. Provide concrete fill-in examples.

Screenshots: Rules and Limitations

Screenshots speed up understanding, but create a maintenance problem — they become outdated when the interface is updated.

Rule: a screenshot is only needed for non-obvious interface elements. If a button is labeled "Add element" and clearly visible — no screenshot needed. If the required option is hidden in a third-level submenu — a screenshot is required.

Screenshot requirements:

• Resolution: 1920×1080 or higher
• Format: PNG (not JPEG — text loses quality)
• Annotations: arrows and highlights via Figma, Snagit, or similar
• Storage: in the git repository alongside documentation, named step-01-open-menu.png

Online Store Manager Manual

The most in-demand workflows for an online store manager on Bitrix:

Processing an order:

1. Store → Orders → Order list
2. Filter: status "New", click "Apply"
3. Open order, verify contents and delivery address
4. Click "Edit", change status to "Accepted for processing", click "Save"
5. Customer will receive an automatic email notification

Product return:

• Don't delete the order — create a return via the "Create return" button in the order
• Specify the items to return and the reason
• After approval — change order status to "Return processed"

Promotions and discounts:

• Store → Marketing → Price rules
• Each rule: condition (from amount, for user group, for section) + action (% discount, fixed discount, gift)
• Priority: lower number = higher priority. A rule with priority 10 applies before a rule with priority 100

Format and Tools

Confluence/Notion — for teams with access to corporate tools. Convenient for maintaining up-to-date content and adding comments.

PDF/DOCX — for official delivery to the client. Generated from Markdown or Google Docs.

Built-in CMS help — tooltip buttons directly in Bitrix admin forms. Implemented via CAdminHint or by adding title attributes to fields in the custom admin interface.

Video instructions — for complex operations with many steps. A 3–5 minute screencast is often more effective than written instructions. Important: keep the project file (Camtasia, Loom) so you can re-record a changed section.

Updating the Manual

Instructions without maintenance are useless. Build updates into the development process:

• In a UI change task — checkbox "Update user manual"
• After each Bitrix update — review changed sections of the admin panel
• Quarterly review: go through all manual scenarios and verify their accuracy

Work Stages

Total: 2–4 weeks depending on the scope of functionality.