Clean up docs for dependencies validationfeature/sm/34834-missing-dependency-should-fail-job-2

3 files changed, 63 insertions, 16 deletions

diff --git a/doc/administration/job_artifacts.md b/doc/administration/job_artifacts.md
index 86b436d89dd..33f8a69c249 100644
--- a/doc/administration/job_artifacts.md
+++ b/doc/administration/job_artifacts.md
@@ -128,6 +128,45 @@ steps below.
 
 1. Save the file and [restart GitLab][] for the changes to take effect.
 
+## Validation for dependencies
+
+> Introduced in GitLab 10.3.
+
+To disable [the dependencies validation](../ci/yaml/README.md#when-a-dependent-job-will-fail),
+you can flip the feature flag from a Rails console.
+
+---
+
+**In Omnibus installations:**
+
+1. Enter the Rails console:
+
+    ```sh
+    sudo gitlab-rails console
+    ```
+
+1. Flip the switch and disable it:
+
+    ```ruby
+    Feature.enable('ci_disable_validates_dependencies')
+    ```
+---
+
+**In installations from source:**
+
+1. Enter the Rails console:
+
+    ```sh
+    cd /home/git/gitlab
+    RAILS_ENV=production sudo -u git -H bundle exec rails console
+    ```
+
+1. Flip the switch and disable it:
+
+    ```ruby
+    Feature.enable('ci_disable_validates_dependencies')
+    ```
+
 ## Set the maximum file size of the artifacts
 
 Provided the artifacts are enabled, you can change the maximum file size of the
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index ac5d99c71fc..32464cbb259 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -1153,15 +1153,19 @@ deploy:
   script: make deploy
 ```
 
->**Note:**
-> Introduced in GitLab 10.3
-> This is the user documentation. For the administration guide see
-  [administration/job_artifacts](../../../administration/job_artifacts.md#validation_for_dependency).
+#### When a dependent job will fail
+
+> Introduced in GitLab 10.3.
 
-If a depended job doesn't have artifacts by the following reason, the depending job will fail.
+If the artifacts of the job that is set as a dependency have been
+[expired](#artifacts-expire_in) or
+[erased](../../user/project/pipelines/job_artifacts.md#erasing-artifacts), then
+the dependent job will fail.
 
-1. A depended `artifacts` has been [erased](https://docs.gitlab.com/ee/api/jobs.html#erase-a-job).
-1. A depended `artifacts` has been [expired](https://docs.gitlab.com/ee/ci/yaml/#artifacts-expire_in).
+NOTE: **Note:**
+You can ask your administrator to
+[flip this switch](../../administration/job_artifacts.md#validation-for-dependencies)
+and bring back the old behavior.
 
 ### before_script and after_script
 
diff --git a/doc/user/project/pipelines/job_artifacts.md b/doc/user/project/pipelines/job_artifacts.md
index f8675f77856..402989f4508 100644
--- a/doc/user/project/pipelines/job_artifacts.md
+++ b/doc/user/project/pipelines/job_artifacts.md
@@ -44,7 +44,7 @@ the artifacts will be kept forever.
 For more examples on artifacts, follow the [artifacts reference in
 `.gitlab-ci.yml`](../../../ci/yaml/README.md#artifacts).
 
-## Browsing job artifacts
+## Browsing artifacts
 
 >**Note:**
 With GitLab 9.2, PDFs, images, videos and other formats can be previewed
@@ -77,7 +77,7 @@ one HTML file that you can view directly online when
 
 ---
 
-## Downloading job artifacts
+## Downloading artifacts
 
 If you need to download the whole archive, there are buttons in various places
 inside GitLab that make that possible.
@@ -102,7 +102,7 @@ inside GitLab that make that possible.
 
     ![Job artifacts browser](img/job_artifacts_browser.png)
 
-## Downloading the latest job artifacts
+## Downloading the latest artifacts
 
 It is possible to download the latest artifacts of a job via a well known URL
 so you can use it for scripting purposes.
@@ -163,14 +163,18 @@ information in the UI.
 
 ![Latest artifacts button](img/job_latest_artifacts_browser.png)
 
-## Validation for `dependency` keyword
+## Erasing artifacts
 
-To disable [the validation for dependency], you can flip the feature flag from a rails console:
+DANGER: **Warning:**
+This is a destructive action that leads to data loss. Use with caution.
 
-```
-Feature.enable('ci_disable_validates_dependencies')
-```
+If you have at least Developer [permissions](../../permissions.md#gitlab-ci-cd-permissions)
+on the project, you can erase a single job via the UI which will also remove the
+artifacts and the job's trace.
+
+1. Navigate to a job's page.
+1. Click the trash icon at the top right of the job's trace.
+1. Confirm the deletion.
 
 [expiry date]: ../../../ci/yaml/README.md#artifacts-expire_in
-[the validation for dependency]: ../../../ci/yaml/README.md#dependencies
 [ce-14399]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14399