Merge pull request #117 from packagist/conductor

Conductor: further explain setup steps

Author: glaubinix

docs/conductor/getting-started.md

@@ -1,25 +1,32 @@
 # Getting started with Conductor
 ##
 
-Conductor will group and schedule automated dependency updates on your own Continuous Integration platform. If the update succeeds, Conductor sends you a pull request to your code hosting platform (GitHub, GitLab, Bitbucket) with the changed composer.lock file and, if necessary, other files modified by Composer plugins or scripts.
+Conductor will group and schedule automated dependency updates on your own continuous integration platform. If the update succeeds, Conductor will send you a pull request to your code hosting platform (GitHub, GitLab, Bitbucket) with the changed composer.lock file and, if necessary, other files modified by Composer plugins or scripts.
 
-To use Conductor:
+Prerequisites for receiving dependency update PRs from Conductor:
 
-- You need to be approved for early access to Conductor. [Join to the waitlist](/features/conductor) and wait for approval.
-- You need a Private Packagist trial or subscription on the cloud plan.
-- You need to add a workflow to your Continuous Integration platform to run Composer updates, described below.
+- Receive early access to Conductor. [Join the waitlist](/features/conductor) and wait for approval.
+- Set up an organization on Private Packagist Cloud either with a free trial or subscribe to the cloud plan.
+- A synchronization in your Private Packagist organization with your code hosting platform.
+- A workflow on your continuous integration platform to run Composer updates.
 
-## Add packages to update automatically
+## Set up synchronization
 
-Once you have a Private Packagist organization and Conductor is enabled for you, log into your Private Packagist organization and click on the "Updates" tab in the main navigation.  
+Once you have a Private Packagist organization and Conductor is enabled for you, log into your Private Packagist organization and head to the "Settings" tab in the main navigation.
+Under the "Synchronization" entry you can add [one or more synchronizations](/features/integration-github-bitbucket-gitlab.md) with an organization on your code hosting platform.
+This is how you grant us access to your VCS repositories. The synchronization will automatically add any repository with a composer.json file in the root directory as a package to Private Packagist.
 
-Conductor will manage dependencies for packages added to Private Packagist [via synchronization](/features/integration-github-bitbucket-gitlab.md) that have a composer.lock file committed to the repository.
+## Configure Conductor for your packages
 
-## Create a workflow on your CI
+Access the "Conductor" tab in the main navigation to see a list of available packages that can have their dependencies updated by Conductor.
+Each package shown is linked to its VCS repository to which Conductor will send pull requests with dependency updates. Your Composer projects or applications are also a kind of package and must be added to Private Packagist as regular packages to use Conductor on them.
+Conductor can only manage dependencies for packages added to Private Packagist [via synchronization](/features/integration-github-bitbucket-gitlab.md) that have a composer.lock file committed to the repository.
+
+To get started, click on the configure link displayed next to the package which you would like Conductor to update. Follow the instructions for your continuous integration platform.
 
 ### GitHub Actions
 
-Create a new GitHub Actions workflow in `.github/workflows/dependency-update.yaml` of your GitHub repository using the template below:
+Create a new GitHub Actions workflow in `.github/workflows/conductor.yaml` of your GitHub repository using the template below:
 
 CONDUCTOR_GITHUB_ACTIONS_WORKFLOW
 
@@ -31,16 +38,19 @@ We recommend to create a dedicated authentication token with update access. You
 
 ![Create Authentication Token](/Resources/public/img/docs/conductor/authentication-token.png)
 
-The contents of the variable should look like 
+The contents of the variable should look like this:
 
 ```json
 {"http-basic": {"repo.packagist.com": {"username": "token", "password": "packagist_out_73a81c..." }}}
 ```
 
-Conductor needs to verify your CI setup before you can start receiving pull requests.
+Conductor needs to verify your CI setup before you can start receiving PRs.
 
 ## Verify your CI setup
 
+- Navigate to the "Conductor" tab in your Private Packagist organization.
+- Click on the name of your package.
+
 ![Task list with verification task](/Resources/public/img/docs/conductor/verification-task-list.png)
 
 Right now all tasks are waiting for the CI verification task on top of the list. Conductor will not start with the regular schedule until this verification task was successful.
@@ -58,9 +68,6 @@ When you run into errors, troubleshoot and fix them. You can trigger the workflo
 
 ## How scheduling works
 
-- Navigate to the "Updates" tab in your Private Packagist organization 
-- Click on the name of your package
-
 The list shows groups of all available updates to be scheduled. Each group of updates is called a task. Conductor will schedule only one task at a time. All others are waiting for the task on top of the list to be successful or paused.  
 Once Conductor schedules a task it sends a payload to your CI platform that triggers the workflow you just added. The payload contains the commands Composer will run to update a group of dependencies from your package.
 
@@ -79,7 +86,7 @@ If all these steps succeeded, Private Packagist creates a pull request for the n
 ![Conductor Pull Request](https://packagist.com/img/features/auto-updates/merged-PR-for-a-security-updated.png)
 
 Once you reviewed the changes and merged the PR, Conductor will schedule the next task.      
-If you close the PR, the task will be paused and Conductor will schedule the next task. This is the same effect as using the "Pause" button in the UI. Conductor won't attempt to update the dependency to this exact version again but will schedule updates with newer versions.  
+If you close the PR, the task will be paused and Conductor will schedule the next task. Clicking the "Pause" button in the UI has the same effect. Conductor won't attempt to update the dependency to this exact version again but it will schedule updates to newer versions.
 
 If you want to schedule any other task in the list, click on its name and use the button "Schedule now to create a PR".