Docs: update visual diff docs (#12453)

Extracted from #12276

Author: stsewd

docs/user/img/build-overview-comment.png

@@ -1,46 +1,99 @@
 Visual 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 :doc:`pull request </pull-requests>` 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 seeing changes in source files is helpful,
+it can be difficult to understand how those changes will look in the rendered documentation,
+or their impact on the documentation as a whole.
+Read the Docs makes it easy to see the changes in the rendered documentation.
 
-Using Visual diff
------------------
+Show diff menu in preview
+-------------------------
 
-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).
+To enable or disable this feature for your project:
 
-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.
+#. Go the :guilabel:`Settings` tab of your project.
+#. Click on :guilabel:`Addons`, and click on :guilabel:`Visual diff`.
+#. Check or uncheck the :guilabel:`Enable visual diff` option.
+#. Click on :guilabel:`Save`.
+
+When 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.
 
 .. 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 shows all the sections that have changed, highlighting their differences with red/green background colors.
+You can jump between each of these chunks by clinking on the up/down arrows.
+
+Show build overview in pull requests
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note::
+
+   This feature is only available for projects connected to a :ref:`reference/git-integration:GitHub App`.
+
+To enable or disable this feature for your project:
+
+#. Go the :guilabel:`Settings` tab of your project.
+#. Click on :guilabel:`Pull request builds`.
+#. Check or uncheck the :guilabel:`Show build overview in a comment` option.
+#. Click on :guilabel:`Update`.
+
+When enabled, a comment is added to the pull request when changes are detected between the pull request and the latest version of the documentation.
+
+.. figure:: /img/build-overview-comment.png
+
+General settings
+----------------
+
+Ignored files
+~~~~~~~~~~~~~
+
+You can configure a list of files or patterns to be ignored when listing the files that changed in the pull request.
+This is useful when you have files that have a date in them,
+or listing/archive files that show changes without content changes in those files.
+
+#. Go the :guilabel:`Settings` tab of your project.
+#. Click on :guilabel:`Addons`, and click on :guilabel:`File tree diff`.
+#. In the :guilabel:`Ignored files` field, add one or more patterns to ignore, one per line.
+#. Click on :guilabel:`Save`.
+
+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 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.
+- ``*`` matches everything, including slashes.
+- ``?`` matches any single character.
+- ``[seq]`` matches any character in ``seq``.
 
-Configuring Visual Diff
------------------------
+Base version
+~~~~~~~~~~~~
 
-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.
+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.
+This is useful if your ``latest`` version doesn't point the default branch of your repository.
 
-Troubleshooting Visual diff
----------------------------
+.. note::
 
-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.
+   This option can be changed by contacting :doc:`/support`.
 
-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.
+- The diff considers HTML files only.
+- 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 gets out of sync with its base branch, the diff may not be accurate, and may show unrelated files and 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 commit 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 happen when the underlying HTML changes without a corresponding visual change, for example, if a link's URL is updated
+- 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.