Refactor and fix pipeline schedules

1 files changed, 66 insertions, 55 deletions

diff --git a/doc/user/project/pipelines/schedules.md b/doc/user/project/pipelines/schedules.md
index 2911a56cf67..89f1beb6d1f 100644
--- a/doc/user/project/pipelines/schedules.md
+++ b/doc/user/project/pipelines/schedules.md
@@ -2,29 +2,33 @@
 
 > **Notes**:
 >
-> - This feature was introduced in 9.1 as [Trigger Schedule][ce-10533].
-> - In 9.2, the feature was [renamed to Pipeline Schedule][ce-10853].
+> - Introduced in GitLab 9.1 as [Trigger Schedule](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10533).
+> - [Renamed to Pipeline Schedule](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10853) in GitLab 9.2.
 > - Cron notation is parsed by [Fugit](https://github.com/floraison/fugit).
 
-Pipeline schedules can be used to run a pipeline at specific intervals, for example every
-month on the 22nd for a certain branch.
+Pipelines are normally run based on certain conditions being met. For example, when a branch is pushed to repository.
 
-## Using Pipeline schedules
+Pipeline schedules can be used to also run [pipelines](../../../ci/pipelines.md) at specific intervals. For example:
 
-In order to schedule a pipeline:
+- Every month on the 22nd for a certain branch.
+- Once every day.
 
-1. Navigate to your project's **CI / CD ➔ Schedules** and click the
-   **New Schedule** button.
-1. Fill in the form
-1. Hit **Save pipeline schedule** for the changes to take effect.
+In addition to using the GitLab UI, pipeline schedules can be maintained using the
+[Pipeline schedules API](../../../api/pipeline_schedules.md).
+
+## Configuring pipeline schedules
+
+To schedule a pipeline for project:
+
+1. Navigate to the project's **CI / CD > Schedules** page.
+1. Click the **New schedule** button.
+1. Fill in the **Schedule a new pipeline** form.
+1. Click the **Save pipeline schedule** button.
 
 ![New Schedule Form](img/pipeline_schedules_new_form.png)
 
-> **Attention:**
-The pipelines won't be executed precisely, because schedules are handled by
-Sidekiq, which runs according to its interval.
-See [advanced admin configuration](#advanced-admin-configuration) for more
-information.
+NOTE: **Note:**
+Pipelines execution [timing is dependent](#advanced-configuration) on Sidekiq's own schedule.
 
 In the **Schedules** index page you can see a list of the pipelines that are
 scheduled to run. The next run is automatically calculated by the server GitLab
@@ -32,36 +36,24 @@ is installed on.
 
 ![Schedules list](img/pipeline_schedules_list.png)
 
-### Running a scheduled pipeline manually
-
-> [Introduced][ce-15700] in GitLab 10.4.
-
-To trigger a pipeline schedule manually, click the "Play" button:
-
-![Play Pipeline Schedule](img/pipeline_schedule_play.png)
-
-This will schedule a background job to run the pipeline schedule. A flash
-message will provide a link to the CI/CD Pipeline index page.
-
-To help avoid abuse, users are rate limited to triggering a pipeline once per
-minute.
-
-### Making use of scheduled pipeline variables
+### Using variables
 
-> [Introduced][ce-12328] in GitLab 9.4.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12328) in GitLab 9.4.
 
 You can pass any number of arbitrary variables and they will be available in
-GitLab CI so that they can be used in your `.gitlab-ci.yml` file.
+GitLab CI so that they can be used in your [`.gitlab-ci.yml` file](../../../ci/yaml/README.md).
 
 ![Scheduled pipeline variables](img/pipeline_schedule_variables.png)
 
-## Using only and except
+### Using only and except
 
 To configure that a job can be executed only when the pipeline has been
 scheduled (or the opposite), you can use
 [only and except](../../../ci/yaml/README.md#onlyexcept-basic) configuration keywords.
 
-```
+For example:
+
+```yaml
 job:on-schedule:
   only:
     - schedules
@@ -75,11 +67,47 @@ job:
     - make build
 ```
 
-## Taking ownership
+### Advanced configuration
+
+The pipelines won't be executed exactly on schedule because schedules are handled by
+Sidekiq, which runs according to its interval.
+
+For example, only two pipelines will be created per day if:
 
-Pipelines are executed as a user, who owns a schedule. This influences what
-projects and other resources the pipeline has access to. If a user does not own
-a pipeline, you can take ownership by clicking the **Take ownership** button.
+- You set a schedule to create a pipeline every minute (`* * * * *`).
+- The Sidekiq worker runs on 00:00 and 12:00 every day (`0 */12 * * *`).
+
+To change the Sidekiq worker's frequency:
+
+1. Edit the `pipeline_schedule_worker_cron` value in your instance's `gitlab.rb` file.
+1. [Restart GitLab](../../../administration/restart_gitlab.md).
+
+For GitLab.com, refer to the [dedicated settings page](../../gitlab_com/index.md#cron-jobs).
+
+## Working with scheduled pipelines
+
+Once configured, GitLab supports many functions for working with scheduled pipelines.
+
+### Running manually
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/15700) in GitLab 10.4.
+
+To trigger a pipeline schedule manually, click the "Play" button:
+
+![Play Pipeline Schedule](img/pipeline_schedule_play.png)
+
+This will schedule a background job to run the pipeline schedule. A flash
+message will provide a link to the CI/CD Pipeline index page.
+
+NOTE: **Note:**
+To help avoid abuse, users are rate limited to triggering a pipeline once per
+minute.
+
+### Taking ownership
+
+Pipelines are executed as a user, who owns a schedule. This influences what projects and other resources the pipeline has access to.
+
+If a user does not own a pipeline, you can take ownership by clicking the **Take ownership** button.
 The next time a pipeline is scheduled, your credentials will be used.
 
 ![Schedules list](img/pipeline_schedules_ownership.png)
@@ -90,20 +118,3 @@ on the target branch, the schedule will stop creating new pipelines. This can
 happen if, for example, the owner is blocked or removed from the project, or
 the target branch or tag is protected. In this case, someone with sufficient
 privileges must take ownership of the schedule.
-
-## Advanced admin configuration
-
-The pipelines won't be executed precisely, because schedules are handled by
-Sidekiq, which runs according to its interval. For example, if you set a
-schedule to create a pipeline every minute (`* * * * *`) and the Sidekiq worker
-runs on 00:00 and 12:00 every day (`0 */12 * * *`), only 2 pipelines will be
-created per day. To change the Sidekiq worker's frequency, you have to edit the
-`pipeline_schedule_worker_cron` value in your `gitlab.rb` and restart GitLab.
-For GitLab.com, you can check the [dedicated settings page][settings]. If you
-don't have admin access to the server, ask your administrator.
-
-[ce-10533]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10533
-[ce-10853]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10853
-[ce-12328]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12328
-[ce-15700]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/15700
-[settings]: https://about.gitlab.com/gitlab-com/settings/#cron-jobs