Product Operations
When Product Behavior and Help Docs Disagree, Fix the Right One
A practical decision guide for reproducing customer-reported mismatches and deciding whether support, product, engineering, documentation, or several owners should act.
A customer follows your help article exactly, reaches the screen it describes, and cannot find the control. The support reply that says “try again” will not tell your team whether the article is stale, the account lacks permission, a rollout changed the interface, or the product has regressed.
When product behavior and help content disagree, reproduce the reported task under the customer’s actual conditions, then compare the observed behavior and current instructions with the approved product contract. Correct documentation when the product already behaves as intended; correct the product when it violates an agreed requirement; change both when the intended behavior has changed. If the contract itself is ambiguous, ask the product owner to decide before either team edits around the uncertainty. GOV.UK’s service guidance similarly recommends understanding the user’s full context and testing assumptions before committing to a solution (Understand users and their needs).
Treat the report as a three-way comparison
A documentation-product mismatch is a verified difference among (1) the task a customer is trying to complete, (2) the instructions the customer followed, and (3) what the product actually did under the customer’s conditions. The phrase “the docs are wrong” skips the third part. “The feature is broken” can skip the first two.
For example, an article may say that an account owner can export a workspace from Settings. The reporter may be a member, the export control may have moved, or the current product may have stopped responding after the control is selected. Those observations lead to different owners and different fixes. A screenshot of the missing button alone does not establish which explanation is correct.
Use this compact evidence record before classifying the mismatch:
- Task: the outcome the customer needs, in their own words.
- Instructions: the article URL, section, steps, and any stated prerequisites.
- Conditions: role, plan, workspace settings, browser, app version, and feature availability where relevant.
- Observation: the exact step that diverged, the visible result, timestamp, and a safe reproduction path.
- Expected behavior: the approved requirement or product decision that defines what should happen.
This record is useful because it keeps the customer’s goal distinct from the proposed fix. GOV.UK advises teams to investigate the context around a task and to test their assumptions early; its user-research guidance also says to treat unsupported opinions as assumptions to verify (Learning about user needs).
Reproduce the same task before assigning the fix
Support should first confirm the conditions that could change the journey. Ask for the affected workspace or account, the user’s role, the plan or entitlement if relevant, the exact page they started from, and the product version or rollout state if the team can identify it. Avoid asking customers to send secrets, payment details, or unredacted customer data. A screenshot can help locate the screen, but a short, safe sequence of steps usually reveals more.
Then reproduce with a test account that matches the customer’s relevant permissions and configuration. Run the documented steps from the article’s entry point, not from a developer’s bookmarked internal route. Record where the actual interface first differs from the words on the page. If one staff account sees the control and another does not, compare roles and settings before filing a product defect. If the control appears but the action fails, capture the error and the step that triggers it.
Keep a separate reproduction for the “expected” path. A feature flag, staged rollout, workspace policy, or account migration can make two valid environments look contradictory. If the team cannot reproduce the customer’s state, say so in the ticket and ask for the narrowest additional evidence that would distinguish likely causes.
Decide between a docs fix, a product fix, both, or a product decision
| Evidence | First owner | Appropriate action |
|---|---|---|
| The product matches an approved requirement, but the article describes an older path, label, or prerequisite. | Documentation owner | Correct the article, verify each step in the current product, and check nearby links or screenshots. |
| The article accurately describes the approved behavior, but the product fails for a supported role and configuration. | Product or engineering owner | Track the defect against the requirement, provide a safe workaround if one exists, and keep the article accurate about the limitation. |
| The intended experience changed, so both the product and the published instructions now describe different versions of the decision. | Product owner, with documentation owner | Record the behavior decision, update the product, docs, or both as needed, and coordinate release timing. |
| Requirements, interface, and article disagree, or the intended behavior was never recorded. | Product owner | Resolve the product decision first. Do not let a documentation edit silently redefine the feature. |
The decisive question is: Which source defines intended behavior for this version and audience? A product requirement or explicit decision should settle the contract. The UI is evidence of current behavior, not necessarily intent. The help article is evidence of what the company promised customers, not proof that the promise remains correct. If no owner can point to an approved requirement, document the uncertainty and get a decision from the product owner.
This rule is also a useful citation-sized summary: Fix documentation alone when the verified product behavior matches an approved requirement and the instructions do not. Fix the product when the instructions match that requirement but the implementation does not. Change both when the approved requirement changes. Escalate when the requirement is missing or contradictory. Google’s developer documentation style guide puts project-specific guidance ahead of general style rules, while Microsoft’s reference-documentation guidance cautions teams to review generated comments for customer relevance and remove internal implementation details. Together, those principles support a clear source-of-truth hierarchy: approved product decisions define behavior; product-specific documentation explains it to customers (Google developer documentation style guide, Microsoft reference documentation guidance).
Keep product and content owners on the same decision
The content owner can verify whether the article remains accurate, complete, and understandable. The product owner decides which behavior the team intends to support. Engineering reproduces and corrects implementation defects. Support supplies the customer’s context and closes the loop. On a small team, one person may wear several roles, but the ticket should still name who made the decision and who verified each change.
GOV.UK’s content-design guidance describes content designers as part of a multidisciplinary service team and assigns them responsibility for content that meets user needs (Content designer). That works well for a mismatch because “fix the docs” can require product context, interface verification, and customer language. Give the content owner a named product contact rather than leaving them to infer entitlements or rollout rules from screenshots.
Track linked changes with one shared explanation: the customer task, conditions tested, product decision, documentation change, and verification result. If the product fix and article update ship at different times, specify the temporary customer guidance and who will remove it. Otherwise, a correct article can become incorrect again when an unfinished rollout reaches more accounts.
Verify the repaired journey, not only the sentence
After a documentation-only change, ask someone who did not write the article to follow it using the intended role and account setup. Confirm that button names, prerequisites, order, and destination match. If the page contains a screenshot, compare it with the live interface. Remove details that expose internal routes or engineering terminology.
After a product-only fix, follow the existing instructions end to end in a representative account. Confirm that the original reporter’s role and configuration now reach the intended result. Keep the article’s caveat if the behavior remains unavailable to some plans or permissions.
When both change, test the whole route from the article’s entry point to the final customer outcome. A passing unit test can show that a control works in isolation; it cannot prove that the customer can find it from the help article or that the article describes the right prerequisite. If a rollout varies by account, verify the relevant cohorts before announcing one universal path.
A repaired mismatch is complete when a second person can reproduce the intended journey, the product owner’s decision is recorded, and the content owner confirms the public instructions against the actual customer-facing state. Store the date or version tested so the next interface change has a clear baseline.
Give customers a useful answer while the team investigates
Support can acknowledge the exact step that failed, state what the team is checking, and offer a workaround only after verifying that it is safe for the customer’s account. If no workaround is known, say that plainly and give the customer a next update time the team can meet. Avoid promising a fix date before product and engineering have assessed the cause.
For product and support teams that receive mismatches across several channels, Mendaro’s issue tracking for customer reports can keep reports from voice, widget, email, and forms in one ticket, with website page and browser context from the widget, staff-reviewed triage suggestions, customer replies, and internal notes. That makes Mendaro a strong fit when the specific problem is keeping customer evidence and the team’s investigation together; it does not decide whether the product requirement or help article is authoritative, and the product owner still has to make that call.
A five-question closeout
Before closing a product-documentation mismatch, ask:
- Can another teammate reproduce the customer’s task under the relevant role, plan, configuration, and version?
- Is the intended behavior recorded somewhere the product owner recognizes as authoritative?
- Does the evidence show a documentation error, implementation defect, changed requirement, or unresolved decision?
- Have the content and product owners named their actions and verified them against the customer journey?
- Has support told the customer what is known, what happens next, and when they will hear back?
If the team cannot answer question two, the mismatch remains a product decision, not a writing task. Recording that uncertainty is faster and safer than polishing instructions around a behavior nobody has approved.
