Blog / Framer & site building /

Documenting a framer plugin without confusing users

A plugin solves a problem for the person who built it. Then the documentation assumes every user already knows the setup.

You can guess what happens next. Support questions, confused settings, and people staring at the screen wondering whether the thing is even working.

Clear documentation starts with the task your user wants to finish, and walks them through it without making them guess. I started doing client plugin work in Framer early this year, and this is the lesson I’d pass on first, on any platform: documentation is part of the product, not a chore you leave until after the build.

Start with the user’s first question

Before writing any instructions, list what a new user needs to know: what the plugin does, what it doesn’t do, who it suits, what access or setup it needs and how to tell it’s working. Put the main purpose at the top. Don’t open with a long story about how the plugin was built.

Use the names people see in the interface. If a setting has a label, repeat it exactly and say where to find it. Users shouldn’t have to translate internal component names or developer shorthand.

Write one task at a time

Organise the guide around outcomes: install, configure, preview, publish, troubleshoot and remove. Each step should say what to do and what the user should see next. If a step depends on a plan, an account permission or another integration, say so before the user hits a dead end.

Screenshots help when they show a meaningful control, but they need labels and an up-to-date interface. Update them when the plugin changes. A screenshot isn’t a substitute for text; the user should still understand the task with assistive technology, or when the interface looks slightly different.

Explain limits and failure states

Tell users what the plugin can’t do, which page types it supports and what happens when required data is missing. Explain how to spot a configuration problem and what to include when asking for help. Don’t promise compatibility with every site or template unless you’ve checked.

Keep troubleshooting advice safe. Don’t ask users to paste secrets, switch off security controls or change production code without a backup. If the fix needs developer access, say so plainly and list the evidence the developer will need.

Make updates easier to follow

When a release changes behaviour, update the relevant guide and note the version or date where it helps. Keep a short changelog of user-facing changes. If a setting moves, search the docs for old instructions and screenshots.

Someone who didn’t write the original guide may ship the next update. Store the docs with the project, make the owner visible and add a docs check to release review. Then ask someone who doesn’t know the code to follow the steps. They’ll find the assumptions the builder stopped noticing long ago.

Use support questions to improve the docs

Support requests show where the guide is unclear. Just don’t copy a user’s private details into public docs. Turn the underlying issue into a general instruction, confirm it with the product owner and update the step. If the question exposes a bug, fix the behaviour. Don’t document a workaround as if it were the intended path.

Document the error path too

Users need to know what to do when the expected result doesn’t appear. Add a short troubleshooting path: confirm the plugin is enabled, check required fields, check the page type and try a safe preview. Say what helps support diagnose the problem, such as the page URL and the visible error message. Never ask users to send passwords or private account tokens.

If the plugin depends on a third-party integration, say so and link to its setup requirements. Tell users what to expect if that service is down. Good docs set boundaries; they don’t only describe the happy path.

Test the guide as part of the build

Ask someone who didn’t build the plugin to follow the docs from a fresh project or clean account. Watch where they hesitate. If they can’t tell a preview from a published change, fix the wording before release. Check headings, links and screenshots on mobile.

When a client plugin changes, update its guide before or alongside the change. Keep a record of known limits and compatibility checks. Good documentation won’t stop every support question, but it makes answers easier to find and the product easier to trust.

Make the boundary between setup and support clear

Explain which parts of the plugin users can safely configure and which changes need the project owner or a developer. A short support page can say where to report a bug, what details to include and what response to expect, if that commitment exists. Don’t promise a response time or compatibility guarantee unless the client has approved it and can keep it up.

Write for the person who has not met the developer

A plugin guide should make sense to someone seeing the site for the first time. Replace “configure the component” with the actual setting name and the result to expect. Define platform terms only where needed. If a user must contact the client’s administrator, explain why and what to ask for.

Keep a short “before you begin” section for requirements such as access, plan or enabled integrations. It stops people following several steps only to find they can’t do the last one. I’d ask a reader to work through the guide with no verbal hints and note every place they stop.

A good guide reduces uncertainty; it doesn’t pretend the plugin never fails. So here’s your next step: pick one task in your Framer plugin docs and hand it to a new user with no help. Where do they pause, or ask what a word means?