Building a Living User Guide for Your 1C-Bitrix Project
Most guides for Bitrix projects are created once and instantly become outdated: screenshots show menus that no longer exist, instructions lead to missing buttons. We solve this by creating a living document with a clear structure, specific steps, and an update mechanism. With over 5 years of Bitrix project experience and 30+ implemented guides, our specialists ensure the guide is accurate at the time of handover. Our process is guaranteed to keep your documentation up-to-date.
5+ years experience | 30+ completed guides | 2-day free assessment
Contact us to evaluate your project in 2 days. We'll analyze your current documentation for free. Typical savings from implementing a living guide: $2,000–$5,000 per year in reduced support calls.
Problems We Solve
- Different audiences require different depths. A content manager needs step-by-step instructions with button names; a store manager needs order processing scenarios; a developer needs technical documentation. Mixing them into one document is a mistake.
- Instructions without screenshots don't work for beginners, but screenshots become outdated with every update. Balance: illustrate only non-obvious elements. Screenshot-aided instructions are 2–3 times better than text-only instructions for onboarding. A task-based guide speeds up onboarding by 3–5 times compared to traditional menu-based documentation.
- Documentation without an update plan is useless. After a month, half the steps no longer match reality.
According to Wikipedia, technical documentation should be task-oriented to be effective.
Why a User Guide Needs Regular Updates
Any active Bitrix project changes: modules are added, UI updates, business processes evolve. If documentation doesn't keep pace, it becomes misinformation. We recommend adding a checkbox "Update guide" to every development task. This reduces update time from 2 days to 2 hours — a 24x improvement.
How We Do It
We build the guide around tasks, not menu items. Example structure for a content manager:
1. Login and navigation 2. Working with news 2.1. Add a news item 2.2. Edit a published item 2.3. Schedule publication 2.4. Unpublish 3. Working with pages (visual editor, images, SEO) 4. Working with product catalog 4.1. Add a product 4.2. Change price 4.3. Update stock manually Each instruction is specific: "Click the Add element button in the upper right corner" — with the element name and position. We provide field filling examples. We use screenshots only for hidden options — for example, selecting a section in a deep submenu. This approach reduces maintenance costs by 2–3 times — better than static guides, as our practice shows.
Deliverables Included in Our Work
Our work includes the following deliverables:
| Deliverable | Description |
|---|---|
| Team interviews | Identify audience, key scenarios, common mistakes |
| Document structure | Table of contents tied to user tasks, not menu |
| Writing instructions | Step-by-step texts for 3 roles |
| Screenshots & annotations | PNG 1920×1080, highlights via Figma, stored in git |
| Real user testing | Test instructions with a client employee |
| Publication | Confluence/Notion for the team, PDF for the client |
| Maintenance (optional) | Quarterly update under contract |
Cost ranges from $1,500 to $5,000 depending on scope.
Why Text-Only Instructions Are Inefficient
Screenshots make learning 2–3 times faster than text-only, but create obsolescence problems. Our rule: a screenshot is needed only if the button is in a non-obvious place (third-level submenu or hidden under an icon). For basic actions, a precise description suffices — "Save button in the upper right corner of the form". This reduces maintenance costs by 2–3 times compared to screenshot-heavy guides.
How to Update the Guide Without Headaches
We recommend three checkpoints:
- Every interface change task includes a checkbox "Update user guide".
- After a Bitrix update — review the changed sections of the administrative panel.
- Quarterly review: walk through all scenarios and verify accuracy.
Example review checklist:
- Check all links in the guide.
- Update screenshots for changed screens.
- Clarify steps for new features.
- Remove outdated sections.
Detailed cost breakdown
Cost includes analysis ($300–$500), writing ($800–$2000), screenshots ($200–$600), testing ($200–$400), publication ($100–$300). Total: $1,500–$5,000.
Stages and Timeline
| Stage | Content | Duration |
|---|---|---|
| Analysis | Interviews, define audience and tasks | 1–2 days |
| Design | Table of contents, scenarios | 1 day |
| Writing | Step-by-step instructions (no screenshots) | 3–7 days |
| Visualization | Screenshots, annotations | 1–3 days |
| Testing | Real user testing | 1–2 days |
| Publication | Deploy in chosen system | 1 day |
Total: from 2 to 4 weeks. Cost: $1,500–$5,000. With 5+ years of proven experience, we deliver accurately.
For complex operations (e.g., exchange with 1C), we use CommerceML — a proven data exchange standard.