Merge branch 'docs/refactor-merge-request-revisions' into 'master'

Refactor merge requests revisions docs

See merge request !6878

4 files changed, 20 insertions, 10 deletions

diff --git a/doc/user/project/merge_requests/img/versions-compare.png b/doc/user/project/merge_requests/img/versions_compare.png
index 890cae7768c..890cae7768c 100644
--- a/doc/user/project/merge_requests/img/versions-compare.png
+++ b/doc/user/project/merge_requests/img/versions_compare.png
diff --git a/doc/user/project/merge_requests/img/versions-dropdown.png b/doc/user/project/merge_requests/img/versions_dropdown.png
index 9bab9304e14..9bab9304e14 100644
--- a/doc/user/project/merge_requests/img/versions-dropdown.png
+++ b/doc/user/project/merge_requests/img/versions_dropdown.png
diff --git a/doc/user/project/merge_requests/img/versions_system_note.png b/doc/user/project/merge_requests/img/versions_system_note.png
new file mode 100644
index 00000000000..7c9d7715745
--- /dev/null
+++ b/doc/user/project/merge_requests/img/versions_system_note.png
diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md
index 2805fdf635c..77eab7ba5e3 100644
--- a/doc/user/project/merge_requests/versions.md
+++ b/doc/user/project/merge_requests/versions.md
@@ -7,26 +7,36 @@ of merge request diff is created. When you visit a merge request that contains
 more than one pushes, you can select and compare the versions of those merge
 request diffs.
 
-![Merge Request Versions](img/versions.png)
+![Merge request versions](img/versions.png)
+
+---
 
 By default, the latest version of changes is shown. However, you
 can select an older one from version dropdown.
 
-![Merge Request Versions](img/versions-dropdown.png)
+![Merge request versions dropdown](img/versions_dropdown.png)
+
+---
 
-You can also compare the merge request version with older one to see what is
+You can also compare the merge request version with an older one to see what has
 changed since then.
 
-![Merge Request Versions](img/versions-compare.png)
+![Merge request versions compare](img/versions_compare.png)
+
+---
+
+Every time you push new changes to the branch, a link to compare the last
+changes appears as a system note.
 
-Please note that comments are disabled while viewing outdated merge versions
-or comparing to versions other than base.
+![Merge request versions system note](img/versions_system_note.png)
 
 ---
 
->**Note:**
-Merge request versions are based on push not on commit. So, if you pushed 5
-commits in a single push, it will be a single option in the dropdown. If you
-pushed 5 times, that will count for 5 options.
+>**Notes:**
+- Comments are disabled while viewing outdated merge versions or comparing to
+  versions other than base.
+- Merge request versions are based on push not on commit. So, if you pushed 5
+  commits in a single push, it will be a single option in the dropdown. If you
+  pushed 5 times, that will count for 5 options.
 
 [ce-5467]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5467