Rework diff docs

docs/user/visual-diff.rst

@@ -1,46 +1,72 @@
-Visual diff
-===========
+Pull request diff
+=================
 
-Visual diff allows you to see a visual :term:`diff` on a documentation page,
-showing what has changed between the ``latest`` version and the active :doc:`pull request </pull-requests>`.
+Get a list of documentation files that changed between the pull request and the latest version of the documentation,
+and see their differences highlighted visually on the documentation pages.
 
-Visual diff allows you to quickly review changes visually,
-and focus your review on what has changed in the current page.
+While it's helpful to see the changes in source files,
+it can be difficult to understand how those changes will look in the rendered documentation,
+or their impact in the documentation as a whole.
+Read the Docs makes it easy to see the changes in the rendered documentation.
 
-Using Visual diff
------------------
+.. figure:: /img/screenshot-viz-diff-ui.png
+   :width: 80%
+
+Configuration
+-------------
+
+The following options are available:
 
-Visual diff is enabled by default and is only available on pull request builds.
-It works by comparing the current page with the default version of the documentation (e.g. where `/` redirects to).
+Show diff menu in preview
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
-When Visual diff is enabled,
-a new UI element appears at the top right of the page showing a dropdown selector containing all the files that have changed in that pull request build.
+Addon (TBD)
+
+When enabnled, a new UI element appears at the top right of the page showing a dropdown selector containing all the files that have changed in that pull request build.
 
 .. figure:: /img/screenshot-viz-diff-ui.png
    :width: 80%
 
 You can select any of those files from the dropdown to jump directly into that page.
-Once there, you can toggle Visual Diff on and off by pressing the :guilabel:`Show diff` link from the UI element, or pressing the `d` key if you have hotkeys enabled.
+Once there, you can toggle visual diff on and off by pressing the :guilabel:`Show diff` link from the UI element, or pressing the `d` key if you have hotkeys enabled.
 
 Visual diff will show all the sections that have changed and their differences highlighted with red/green background colors.
 Then you can jump between each of these chunks by clinking on the up/down arrows.
 
-Configuring Visual Diff
------------------------
+Show diff in the pull request
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+TBD
+
+Base version
+~~~~~~~~~~~~
+
+The base version is the version of the documentation that is used to compare against the pull request.
+By default, this is the latest version of the documentation.
 
-All the available configuration for the visual diff addon can be found under :guilabel:`Settings > Addons > Visual diff` in the :term:`dashboard`.
-You can choose to disable/enable the `Visual diff` feature on a per project basis.
-Visual diff can also ignore files by specifying these files under `File tree diff`, regex supported.
+Ignore files
+~~~~~~~~~~~~
 
-Troubleshooting Visual diff
----------------------------
+Patterns are matched against the relative paths of the HTML files produced by the build,
+you should try to match ``index.html``, not ``docs/index.rst``, nor ``/en/latest/index.html``.
+Patterns can include one or more of the following special characters:
 
-Visual diff only works when we detect changes on the page,
-so ensure you are on a page that has changed in the current pull request.
+- ``*`` matches everything, including slashes.
+- ``?`` matches any single character.
+- ``[seq]`` matches any character in ``seq``.
 
-There are also some known issues that currently don't display properly.
-We are working to improve the UX, but so far we've found the following issues:
+Limitations and known issues
+----------------------------
 
-* **Tables** are shown to have changes when they may not have changed. This is due to subtle variations in how HTML tables are rendered, and will be fixed in a future version.
-* **Invisible changes** sometimes are marked as diff due than the underlying HTML changing, but there is no visual change. This could happen if the URL of a link changed, for example.
-* **Chunks background is incorrect** when we are unable to detect the correct main parent element for the chunk.
+- Only HTML files are taken into consideration for the diff.
+- The diff is done between the files from the latest successful build of the pull request and the default base version (latest by default).
+  If your pull request get's out of sync with the branch it is based on, the diff may not be accurate, and may show unrelated files an sections as changed.
+- The diff is done by comparing the "main content" of the HTML files.
+  This means that some changes outside the main content, like header or footer, may not be detected.
+  This is done to avoid showing changes that are not relevant to the documentation content itself.
+  Like all pages being marked as changed because of a date or commmit hash being updated in the footer.
+- Invisible changes. Some sections may be highlighted as changed, even when they haven't actually visually changed.
+  This can be due the underlying HTML changing, but there is no visual change, for example, if the URL of a link changed.
+- Tables may be shown to have changes when they have not actually changed.
+  This is due to subtle variations in how HTML tables are rendered, and will be fixed in a future version.
+- The background of diff chunks may be incorrect when we are unable to detect the correct main parent element for the chunk.