What Is a Theme Manual — and Why It Matters
A Theme Manual is a simple user guide you deliver with your theme. It shows merchants how to install the theme, customize it, and use its features — on their own.
A good manual pays off directly:
Fewer repetitive support tickets for you.
Faster setup and a better first impression of your theme.
Higher merchant satisfaction and better reviews.
One rule above all: you are writing for a merchant, not a developer. Assume no technical background. If the merchant needs to contact you to understand a feature, the manual has failed at its job.
What the Manual Must Cover
Keep it short, but don't skip the essentials:
About the theme — one or two lines: what the theme is, and which types of stores it suits.
Installation & activation — how to install the theme and set it as the active theme.
Home page customization — how to add, remove, and reorder sections.
Basic setup — logo, colors, fonts, and menus.
Home page sections — each section and its available options.
Product & category pages — layout options and display settings.
Header & footer — customization options.
Arabic & English setup — how the theme behaves in each language and how to configure both.
Recommended image sizes — exact dimensions for banners, sliders, and product images.
Mobile vs. desktop — which features appear on each, and any differences.
Supported integrations — apps or services the theme works with.
Limitations — what the theme does not support.
Troubleshooting — the most common issues and how to fix them.
Support contact — how to reach you, and your response hours.
How to Write Instructions Merchants Understand
One step per line. Never bundle three actions into one sentence.
Use numbered steps for anything the merchant has to do.
Name things exactly as they appear in the Theme Editor (the visual editor merchants use to customize the theme). If the button says "Save changes," write "Save changes" — not "confirm."
Say where, then what. Start each instruction with the location, then the action.
Show the result. End each task with what the merchant should see when it works.
Avoid technical terms. No "render," or "breakpoint." If a technical term is unavoidable, explain it in plain words the first time.
Example: unclear vs. clear
❌ Unclear:
You can configure the banner from the settings.
✅ Clear:
To change the main banner:
Open the Theme Editor.
Select the Main Banner section.
Click Change image and upload your image (recommended size: 1920 × 600 px).
Click Save.
Result: your new banner appears at the top of the home page.
How to Document Each Feature
For every feature in your theme, cover these points — briefly:
Element | What to write |
Feature name | Exactly as it appears in the Theme Editor |
Purpose | One line: what it does for the store |
Location | Where to find it in the editor |
Steps | Numbered steps to enable or customize it |
Expected result | What the merchant sees when it's set up correctly |
Screenshot | One clear image of the feature or its settings |
Requirements / limits | Anything needed for it to work, or any restriction |
Mobile vs. desktop | Only if the feature looks or behaves differently |
If a feature needs none of the last two rows, skip them — don't pad.
When to Use Images, GIFs, and Videos
Screenshot — the default. Use one whenever you mention a specific screen, section, or setting. Crop to the relevant area and highlight the key button or field.
GIF — for short interactions (3–4 steps), like reordering sections by drag and drop.
Video — only for longer flows, like full theme setup from scratch. Keep it under 3 minutes.
No visuals — for one-step instructions that need no explanation.
Keep screenshots up to date: an outdated screenshot is more confusing than no screenshot.
Be Honest About Requirements and Limitations
This section builds trust and prevents frustrated tickets. State clearly:
Requirements: e.g., "The featured products section requires at least 4 products to display properly."
Limitations: e.g., "The countdown timer supports one active timer at a time."
Not supported: e.g., "This theme does not support right-side navigation on desktop."
A merchant who knows a limit upfront accepts it. A merchant who discovers it after an hour of trying opens a ticket — or leaves a bad review.
Keep the Manual Updated
Update the manual in the same release as any theme change — new feature, renamed setting, or removed option.
Update screenshots when the interface changes.
Show the last updated date and matching theme version at the top of the manual.
Keep a short changelog at the end ("v2.1 — Added testimonials section").
An outdated manual generates more support tickets than having no manual at all, because it actively misleads.
Common Mistakes to Avoid
Writing for developers — code snippets and jargon a merchant can't act on.
Walls of text — long paragraphs instead of short numbered steps.
Vague instructions — "adjust it from the settings" with no location or steps.
No visuals — describing screens in words when one screenshot would do.
Hiding limitations — merchants will find them anyway, the hard way.
Skipping mobile — most store visitors are on mobile; document the differences.
No image sizes — merchants upload wrong-sized banners
Letting it go stale — the theme evolves, the manual doesn't.
Overwriting — a manual that's too long doesn't get read. Cover everything important, in as few words as possible.
Final Checklist Before Delivery
[ ] Covers installation, setup, and every customizable section.
[ ] Written in plain language a non-technical merchant understands.
[ ] All names match the Theme Editor exactly.
[ ] Every task is written as short numbered steps.
[ ] Screenshots included for every key screen — current and clearly cropped.
[ ] Recommended image sizes listed for all banners and images.
[ ] Mobile vs. desktop differences documented.
[ ] Requirements, limitations, and unsupported cases stated clearly.
[ ] Troubleshooting section covers your most common support questions.
[ ] Support contact details and response hours included.
[ ] Available in Arabic and English
[ ] Last updated date and theme version shown at the top.
[ ] Reviewed once by someone non-technical — if they get stuck, revise.
Closing
A clear Theme Manual is part of the product, not an extra. It cuts your support load, helps merchants get value from your theme in minutes instead of days, and reflects directly on your theme's ratings and sales. An hour spent making the manual clearer saves many hours of answering the same question — one ticket at a time.