Comparing product flow revisions helps you identify how an experience has changed between versions and keep the associated documentation accurate. Use this process before reviewing or publishing documentation for a changed product flow.
Overview
Product flows can change when screens, user actions, relationships, or supporting services are updated. The comparison view lets you examine revisions side by side so you can determine whether the documented flow still reflects the current experience.
You will typically use this feature after a new version is available for review, when a change request affects a documented flow, or before selecting Review & Publish. Compare the earlier and later revisions, identify the user-visible impact, then update the documentation where needed.
The comparison workspace can include a source-oriented view and a difference view. Use the available comparison controls to focus on changes, then use Save Changes after you update the documentation.
📷 Screenshot pending: The product flow revision comparison workspace showing version comparison controls and changed content.
Prerequisites
Before you start, make sure you have the following:
- Access to the relevant project and its product flow documentation.
- At least two available revisions or versions to compare.
- Permission to edit the associated documentation if you need to make updates.
- A clear understanding of the flow you are reviewing, including the expected user journey.
- Any supporting change information needed to confirm why the experience changed.
Step-by-Step Instructions
-
Open the project that contains the product flow documentation you want to review.
-
Open the area where the project’s versions or revisions are available.
-
Select Compare Versions to open the version comparison workspace.
-
Choose the revision that represents the earlier version of the product flow.
-
Choose the revision that represents the newer version of the product flow.
-
Select Compare to load the differences between the selected revisions.
-
Review the comparison results to identify additions, removals, and modifications that affect the product flow.
-
Select Source if you need to inspect the source-oriented representation of the changed content.
-
Use the comparison display to review each changed section and determine whether it changes what a user sees or does in the flow.
-
If the comparison identifies a change in the documented experience, open the related product flow documentation for editing.
-
Update the flow description so that it reflects the current user journey, including changed screens, actions, decisions, and outcomes.
-
Update any affected diagrams or visual flow content if the changed experience is represented graphically.
-
Select Save Changes to keep your documentation updates.
-
Select Back to Review when you are ready to return to the documentation review process.
-
Select 1 Review Summary to confirm that the revised documentation and comparison findings are ready for review.
📷 Screenshot pending: A comparison result showing changed product flow content and the Source option.
Tips and Best Practices
-
Compare revisions before you begin editing. This helps you distinguish actual experience changes from wording or formatting differences.
-
Focus on changes that alter the user journey. For example, review changes that add or remove a step, change a decision point, redirect users to another screen, or change the result of an action.
-
Review relationships between parts of the flow, not only individual screens. A component can render another component or use a hook or service, and these changes may indicate that the visible experience or its supporting behavior has changed.
-
Check changes across the relevant product areas. A flow may involve frontend behavior, backend processing, data storage, API schema, configuration, and documentation. Not every technical change needs a user-facing documentation update, but you should verify its effect on the experience.
-
Use Change branch when your organization maintains changes in a different branch or revision context. Confirm that you are comparing the intended versions before selecting Compare.
-
Keep documentation language user-centered. Describe the screen, control, and result that users encounter rather than internal implementation details.
-
Save documentation changes before moving to Review & Publish. Unsaved edits may not be included in the review stage.
-
Use View Changelog when you need additional context about changes included in a version. This can help you validate whether a difference is expected.
Related Pages
- Review Product Flow Documentation
- Update Product Flow Documentation
- Review and Publish Documentation
- View Project Changelog
- Export Documentation
- Request Documentation Changes
Troubleshooting
Compare Versions does not show the revisions you need
Confirm that the required earlier and newer versions are available in the project. If your team uses multiple branches, select Change branch and choose the branch that contains the revisions you need to compare.
The comparison shows changes, but the product flow appears unchanged
Review the changed content carefully in both the regular comparison display and Source view. Some differences may be structural or supporting changes that do not affect the user journey. Update documentation only when the visible experience, user action, decision, or outcome has changed.
You cannot save documentation updates
Verify that you have editing permission for the documentation and that you have made changes in the editable documentation area. After making your updates, select Save Changes again. If the issue continues, return to Back to Review and confirm that the documentation is in the correct review context.
Was this page helpful?