Merge pull request #430 from OpenFn/migration-docs-edit

migration docs edits

docs/migration/converting-triggers.md

@@ -1,6 +1,6 @@
 ---
 title: Converting Triggers from v1 to v2
-sidebar_label: Converting Triggers
+sidebar_label: Converting v1 Triggers
 slug: /converting-triggers
 ---
 

docs/migration/migration-steps.md

@@ -17,41 +17,44 @@ decisions. For customized migration support, ask your questions on our
    custom name and description.
 3. Think about how long you want OpenFn to retain your input and output data and
    configure data storage accordingly.
-4. On v2, the jobs you use for automating tasks are organized in
-   [Workflows](../tutorials/tutorial.md). Build out a skeleton to get started:
-   set up [Triggers](../build/triggers.md) and the key
+4. On v2, the jobs you use for automating tasks are organized as
+   [Workflows](../tutorials/tutorial.md), where each Job is 1 "Step" in a
+   Workflow. Build out a skeleton to get started: set up
+   [Triggers](../build/triggers.md) and the key
    [Steps](https://docs.openfn.org/documentation/build/steps) to get started.
-5. Remember how you can use “On success” or “On failure” of another job to
-   trigger a new one? V2 allows you to do just this, along with setting up
-   custom conditions, using
-   [Paths](https://docs.openfn.org/documentation/build/paths). Follow
-   [our guide on converting your v1 triggers to v2](../migration/converting-triggers.md)
+5. While configuring the Steps in your workflow, consider which _which
+   conditions_ define when the next Step should execute. On v2, you can define
+   [Path conditions](https://docs.openfn.org/documentation/build/paths) to
+   configure whether a Step should run "on success", "on failure", or based on
+   custom logic. Follow
+   [our guide on converting your v1 "triggers" to v2 configuration](../migration/converting-triggers.md)
    to learn more.
-6. You can now add job code. Check out our
-   [detailed docs on building Workflows](../build/workflows.md) to learn more.
-7. Create [Credentials(../build/credentials.md)] for your test and production
-   systems.
-8. For setup and testing, use your test system credentials in your Workflows.
-9. Copy your job code from your GitHub repository or directly from your v1
-   project and paste it into the jobs. Get familiar with the revamped Job
-   Inspector for code editing [here](../build/steps/step-editor.md).
-10. Add custom input and [run your workflow](../build/steps/step-editor.md) to
-    start testing.
-11. Check out the [History](../monitor-history/activity-history.md) page to
-    monitor your Workflow runs.
-12. Test and iterate.
-13. Project version control/GitHub sync has also gone through some changes. To
-    connect your project to GitHub, follow
-    [this guide](../manage-projects/link-to-gh.md).
+6. Once the basic Steps and Paths are configured, copy your job code from your
+   GitHub repository or directly from your v1 project and paste it into each
+   Step's Inspector view. Get familiar with the revamped Job Inspector for code
+   editing [here](../build/steps/step-editor.md).
+7. Make sure the Adaptor and Adaptor Version match your v1 jobs exactly. See the
+   [Steps docs](../build/steps/step-editor.md) for more info on these.
+8. Create [Credentials](../build/credentials.md) for your test and production
+   systems. **First test your workflows using your "test" or "sandbox"
+   credentials.**
+9. Once the Steps are fully configured, add a new custom input and
+   [run your workflow](../build/steps/step-editor.md) to start testing.
+10. Check out the [History](../monitor-history/activity-history.md) page to
+    monitor and review your Workflow runs.
+11. Test and iterate.
+12. Once the Workflow is validated, back up your configuration to Github. The
+    OpenFn-Github version control works differently in v2, so
+    [this guide](../manage-projects/link-to-gh.md) to learn how it works.
 
-    a. Automated migration: It is possible to migrate an entire project from v1
-    to v2 in an automated way. You can do this by going to Project Settings on
-    v1, clicking `Export Config` and choosing `Export for v2 (migrate)`. You
-    will receive a project.yaml file containing your entire project
-    configuration with jobs and triggers. To migrate, commit this file to the
-    Github repo you want to link to your v2 project, and set up the connection
-    as described in the above guide. Your project configuration will be deployed
-    to your v2 project.
+    - **Automated migration**: It is possible to migrate an entire project from
+      v1 to v2 in an automated way. You can do this by going to Project Settings
+      on v1, clicking `Export Config` and choosing `Export for v2 (migrate)`.
+      You will receive a project.yaml file containing your entire project
+      configuration with jobs and triggers. To migrate, commit this file to the
+      Github repo you want to link to your v2 project, and set up the connection
+      as described in the above guide. Your project configuration will be
+      deployed to your v2 project.
 
     :::warning
 
@@ -60,34 +63,49 @@ decisions. For customized migration support, ask your questions on our
 
     :::
 
-    b. NOTE: Once the Github sync is live, consider that all changes will be
-    synced with the project.yaml file. Therefore, any job changes made via
-    Github, must be applied directly to this file. (Unlike the v1 Github sync,
-    edits to individual job files will not sync to the OpenFn v2 app. Rather,
-    all changes must be made in the project.yaml file or within the linked web
-    app).
+    :::tip
 
-14. You may have other design decisions to make, too. For example, if your
+    Once the Github sync is live, consider that all changes will be synced with
+    the project.yaml file. Therefore, any job changes made via Github, must be
+    applied directly to this file. (Unlike the v1 Github sync, edits to
+    individual job files will not sync to the OpenFn v2 app. Rather, all changes
+    must be made in the project.yaml file or within the linked web app).
+
+    :::
+
+13. You may have other design decisions to make, too. For example, if your
     original v1 workflow uses Inbox in between steps, you might need to adjust
     configuration and design so that your jobs are linked together in one
     Workflow (1 Step for each Job you had in the v1 configuration).
 
-15. If you’re using a Webhook Trigger, you can add an extra layer of security by
-    requiring authentication. Note that if you do this, you will need to update
-    the webhook configuration in the external app that points to OpenFn.
-16. Fine-tune your security configuration by following our Project Security and
-    Go-Live Checklist.
-17. Test some more.
-18. When all runs smoothly, switch to production systems from your test systems:
-    update the credentials in your Workflows to point to production systems.
-19. If webhooks are used, update endpoints in your production systems to point
-    to your v2 OpenFn Workflows.
-20. You can monitor usage on your
-    [Workflows Dashboard](../manage-projects/workflow-dashboard.md).
-21. You’re done with your new setup! You can now turn off your jobs on v1 and
-    remove the GitHub connection there.
-22. If you want to export your v1 data for reference or archival, get in touch
+14. If you’re using a Webhook Trigger, you can add an extra layer of security by
+    requiring authentication
+    ([see relevant docs](../manage-projects/webhook-auth.md)). Note that if you
+    do this, you will need to update the webhook configuration in the external
+    app that points to OpenFn.
+15. Fine-tune your security configuration by following our
+    [Project Security and Go-Live Checklist](https://docs.google.com/document/d/1XtiiKszeK5MAltPyqvlL4KCjkHC87YYlX8OPh6fZn4c/edit?usp=sharing)
+    to consider other v2-specific security features
+    ([such as input/output data storage](docs/manage-projects/io-data-storage.md)).
+16. Test some more.
+17. When all workflows run smoothly, update each Step to use a "production"
+    credential to connect to live systems.
+18. If webhooks are used in your source applications, update endpoints in your
+    production systems to point to your v2 OpenFn Workflows.
+19. You’re now done with your new v2 setup! You can monitor usage on your
+    [Workflows Dashboard](../manage-projects/workflow-dashboard.md). Now time to
+    shut down your v1 project.
+20. Turn off your jobs on v1 and remove the GitHub connection there.
+21. If you want to export your v1 data for reference or archival, get in touch
     with us at [[email protected]](mailto://[email protected]).
-23. Finally, when ready, request to delete your project on v1. (The v1 platform
-    will be sunsetted in 2025, and our team will provide regular updates until
-    then.)
+22. Finally, when ready, request to delete your project on v1. To do this, go to
+    your v1 `Project Settings` and select the `Delete Project` button.
+
+::: info 
+
+The OpenFn v1 platform will be sunsetted in 2025. If you need support
+migrating your project, post on [Community](https://community.openfn.org) or
+contact [[email protected]](mailto://[email protected]) for paid support
+options.
+
+:::

sidebars-main.js

@@ -141,10 +141,7 @@ module.exports = {
     {
       type: 'category',
       label: 'Migrate to v2',
-      items: [
-        'migration/converting-triggers',
-        'migration/migration-steps'
-      ],
+      items: ['migration/migration-steps', 'migration/converting-triggers'],
     },
     {
       type: 'link',