Update pipeline template docs for Q3 release

pages/pipelines/templates.md

@@ -7,24 +7,27 @@
 
 Pipeline templates allow you to define standard pipeline step configurations to use across all the pipelines in your organization.
 
-When a pipeline has a template assigned, the pipeline inherits its step configuration from the template. Configuring a custom step configuration for that pipeline in the Buildkite dashboard is no longer possible. This includes any custom command steps.
+When a pipeline has a template assigned, the pipeline inherits its step configuration from the template.
 
-Before assigning a template to a pipeline, you need to [require pipeline templates](#requiring-pipeline-templates) in your organization.
+Before assigning a template to a pipeline, you need to mark that template as available for use in your organization.
 
 ## Creating a pipeline template
 
-Only administrators can create or update pipeline templates.
+Only administrators can create or update pipeline templates. You can do this through the Buildkite UI or the REST and GraphQL APIs.
 
 To create a template:
 
 1. Navigate to your [organization’s pipeline templates](https://buildkite.com/organizations/-/pipeline-templates).
 1. If this is your first template, select _Create a Template_. Otherwise, select _New Template_.
 1. Enter the name and description for your new template.
 1. Update the default step configuration.
+1. Select _Available for assignment by non-admins_ if you would like everyone in your organization to be able to use this template when creating pipelines or editing pipeline steps.
 1. Select _Create Template_.
 
 An administrator can add multiple templates to use across the organization. Making changes and saving a template will apply those changes to all pipelines using that template.
 
+As an administrator you do not need to mark a template available to see it in the available templates dropdown. You will be able to see all the templates you created while creating a new build, creating a new pipeline or editing steps for an existing pipeline.
+
 ## Testing a pipeline template
 
 An administrator can test a pipeline template against a pipeline using the _New Build_ button on the pipeline page.
@@ -35,31 +38,30 @@ If a template exists for the organization, it can be selected from the _Pipeline
 
 The power of pipeline templates comes from how much you require their use. Administrators can select from the following options, listed in increasing strictness:
 
-1. **Do not require pipeline templates:** Pipeline steps remain editable for any user with permission to create or update a pipeline. Templates can be tested (by administrators) against pipelines but cannot be assigned to them.
+1. **Do not require pipeline templates:** Pipeline steps remain editable for any user with permission to create or update a pipeline. Templates marked as available can be assigned to pipelines. Use this option if you would like your pipeline templates to act more like starting guides for users in your organization to create pipelines faster.
 1. **Require a pipeline template on new pipelines:** A template must be selected when creating a new pipeline. The step configuration of existing pipelines will become read-only. Pipelines can be assigned a template individually, making a gradual migration to pipeline templates possible.
 1. **Requiring a pipeline template for everything:** Templates are mandatory on all new and existing pipelines. When choosing this setting, you will select a pipeline template to apply to any pipeline that does not already have a template assigned.
 
->🚧 Changing requirements
-> When updating the requirements, you can only update the setting to an option that is more strict. Take care to test your pipeline templates before enforcing them on all pipelines.
-
 To change your organization's requirements for pipeline templates:
 
 1. Navigate to your [organization's pipeline templates](https://buildkite.com/organizations/-/pipeline-templates).
 1. Check you have at least one template. If you don't have a template, create one.
 1. Select _Settings_.
 1. Select the requirement you want to set.
 
+If you stop requiring pipeline templates for your organization, any pipelines using templates will continue to do so. You can later change their steps settings to remove the template.
+
 ## Assigning a pipeline template to a pipeline
 
-After an administrator requires pipelines to use a template, anyone with permission to create or change a pipeline can assign a template. Assigning a template overrides the pipeline's step configuration with the template.
+After an administrator marks a pipeline template available for use, anyone with permission to create or change a pipeline can assign a template. Assigning a template overrides the pipeline's step configuration with the template.
 
-Once pipeline templates are required, you can use the following methods to assign a template to individual pipelines:
+You can use the following methods to assign a template to a pipeline:
 
 - On the step settings for the pipeline (_Pipeline_ > _Settings_ > _Steps_), select the template to assign.
 - Using the REST API, [update the pipeline](https://buildkite.com/docs/apis/rest-api/pipelines#update-a-pipeline) with the appropriate `pipeline_template_uuid`.
 - Using the GraphQL API, run the [`pipelineUpdate` mutation](https://buildkite.com/docs/apis/graphql/schemas/mutation/pipelineupdate) with the appropriate `pipelineTemplateId`.
 
-You can find the IDs to use for a template with the APIs on the template page in the Buildkite dashboard.
+You can find the IDs for a pipeline template on its page in the Buildkite dashboard.
 
 >📘 Web steps editor compatibility
 > Pipelines defined using the web steps editor cannot be assigned templates through the Buildkite dashboard. These pipelines must be either [migrated to YAML steps first](https://buildkite.com/docs/tutorials/pipeline-upgrade), updated using the APIs, or bulk-assigned a template when selecting the _Require a pipeline template for everything_ setting.