improve browse JUnit details

2 files changed, 12 insertions, 5 deletions

diff --git a/doc/ci/junit_test_reports.md b/doc/ci/junit_test_reports.md
index 3fd54647abb..91a0ae327bf 100644
--- a/doc/ci/junit_test_reports.md
+++ b/doc/ci/junit_test_reports.md
@@ -61,7 +61,7 @@ For a list of supported languages on JUnit tests, check the
 [Wikipedia article](https://en.wikipedia.org/wiki/JUnit#Ports).
 
 To enable the JUnit reports in merge requests, you need to add
-[`artifacts:reports:junit`](yaml/README.md#artifacts-reports-junit)
+[`artifacts:reports:junit`](yaml/README.md#artifactsreportsjunit)
 in `.gitlab-ci.yml`, and specify the path(s) of the generated test reports.
 
 In the following examples, the job in the `test` stage runs and GitLab
@@ -69,6 +69,10 @@ collects the JUnit test report from each job. After each job is executed, the
 XML reports are stored in GitLab as artifacts and their results are shown in the
 merge request widget.
 
+NOTE: **Note:** 
+If you also want the ability to browse JUnit output files, include the
+[`artifacts:paths`](yaml/README.md#artifactspaths) keyword.
+
 ### Ruby example
 
 Use the following job in `.gitlab-ci.yml`:
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index 02f198dbd67..88c1c559947 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -1297,13 +1297,17 @@ GitLab 11.2. Requires GitLab Runner 11.2 and above.
 
 The `reports` keyword is used for collecting test reports from jobs and
 exposing them in GitLab's UI (merge requests, pipeline views). Read how to use
-this with [JUnit reports](#artifacts-reports-junit).
+this with [JUnit reports](#artifactsreportsjunit).
 
 NOTE: **Note:**
 The test reports are collected regardless of the job results (success or failure).
 You can use [`artifacts:expire_in`](#artifacts-expire_in) to set up an expiration
 date for their artifacts.
 
+NOTE: **Note:** 
+If you also want the ability to browse the report output files, include the
+[`artifacts:paths`](#artifactspaths) keyword.
+
 #### `artifacts:reports:junit`
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/20390) in
@@ -1312,8 +1316,9 @@ GitLab 11.2. Requires GitLab Runner 11.2 and above.
 The `junit` report collects [JUnit XML files](https://www.ibm.com/support/knowledgecenter/en/SSQ2R2_14.1.0/com.ibm.rsar.analysis.codereview.cobol.doc/topics/cac_useresults_junit.html)
 as artifacts. Although JUnit was originally developed in Java, there are many
 [third party ports](https://en.wikipedia.org/wiki/JUnit#Ports) for other
-languages like Javascript, Python, Ruby, etc.
+languages like JavaScript, Python, Ruby, etc.
 
+See [JUnit test reports](../junit_test_reports.md) for more details and examples.
 Below is an example of collecting a JUnit XML file from Ruby's RSpec test tool:
 
 ```yaml
@@ -1330,8 +1335,6 @@ rspec:
 The collected JUnit reports will be uploaded to GitLab as an artifact and will
 be automatically shown in merge requests.
 
-For more examples, see [JUnit test reports](../junit_test_reports.md).
-
 NOTE: **Note:**
 In case the JUnit tool you use exports to multiple XML files, you can specify
 multiple test report paths within a single job and they will be automatically