docs: reorganize template docs (#10297)

* docs: rework our "templates" section

* wikistuff

* fix formatting

* add diagram

* reorganize some things

* docs: improve workspaces and templates doc (#9139)

* Reorg, updated/new screenshots, consistent terminology

* First pass

* Another pass

* Added integration section

* New outline for template pages, small updates

* Revised outline for templates, added tutorial

* First pass at tutorial

* Some feedback from Ben.

* Update docs/workspaces.md

Co-authored-by: Muhammad Atif Ali <matifali@live.com>

* Update docs/workspaces.md

Co-authored-by: Muhammad Atif Ali <matifali@live.com>

* Update docs/workspaces.md

Co-authored-by: Muhammad Atif Ali <matifali@live.com>

* Fixed typos

* Expanded tutorial

I have read the CLA Document and I hereby sign the CLA

* New screenshots, improved tutorial, revised anatomy

* Improved tutorial. Anatomy is now a guided tour.

* First pass at guided tour

* Updated authentication info

* Reorganized the guided tour

* Edited more template pages

* Update docs/templates/tour.md

Co-authored-by: Muhammad Atif Ali <matifali@live.com>

* Update docs/templates/tour.md

Co-authored-by: Muhammad Atif Ali <matifali@live.com>

* Update docs/templates/tour.md

Co-authored-by: Muhammad Atif Ali <matifali@live.com>

* Update docs/templates/tutorial.md

Co-authored-by: Muhammad Atif Ali <matifali@live.com>

* Update docs/templates/tour.md

Co-authored-by: Muhammad Atif Ali <matifali@live.com>

* Update docs/templates/tour.md

Co-authored-by: Muhammad Atif Ali <matifali@live.com>

* Update docs/templates/tour.md

Co-authored-by: Muhammad Atif Ali <matifali@live.com>

* Update docs/templates/tour.md

Co-authored-by: Muhammad Atif Ali <matifali@live.com>

* Update docs/templates/tour.md

Co-authored-by: Muhammad Atif Ali <matifali@live.com>

* Revised devcontainers and docker-in-workspaces

* Edited and added screenshots

* Prepared first draft, except docs/templates/open-in-coder.md

* Fix typo

* remove legacy parameters and migration guide

* Use coder templates create

* Added screenshot for workspace template variables

* Made it prettier

* Fixed minor typos and markdown problems

* edits to repairing workspaces

* fix broken links in product

* Added troubleshooting, minor corrections.

* fix terminal links

* fmt

---------

Co-authored-by: Muhammad Atif Ali <matifali@live.com>
Co-authored-by: Ben Potter <me@bpmct.net>
Co-authored-by: Atif Ali <atif@coder.com>

* make fmt

* fix merge conflict

* make fmt

* make gen

* update

* lint

* Discard changes to coderd/database/queries.sql.go

* Discard changes to cli/templates.go

* Discard changes to cli/templateversionarchive.go

* Discard changes to cli/templateversions.go

* Update docker-in-workspaces.md

* replace ```sh with ```shell

* open-in-coder

* fmt

* mention coder_metadata in icons.md

* resource_metadata

* use shell

* modules.md

* mention coder registry module

* workspace.md

* resource_metadata

* remove duplication

* address comments

* cleanup

* fmt

* fix broken links

* fix numbering

* mention module registry

* add example

* demote heading

* remove top level entry from manifest

* fmt

---------

Co-authored-by: Ben <me@bpmct.net>
Co-authored-by: Marc Paquette <22124737+marcpaq@users.noreply.github.com>

docs/templates/authentication.md

@@ -7,31 +7,42 @@
   </p>
 </blockquote>
 
-Coder's provisioner process needs to authenticate with cloud provider APIs to
-provision workspaces. You can either pass credentials to the provisioner as
-parameters or execute Coder in an environment that is authenticated with the
-cloud provider.
+The Coder server's
+[provisioner](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/provisioner)
+process needs to authenticate with other provider APIs to provision workspaces.
+There are two approaches to do this:
 
-We encourage the latter where supported. This approach simplifies the template,
-keeps cloud provider credentials out of Coder's database (making it a less
-valuable target for attackers), and is compatible with agent-based
-authentication schemes (that handle credential rotation and/or ensure the
-credentials are not written to disk).
+- Pass credentials to the provisioner as parameters.
+- Preferred: Execute the Coder server in an environment that is authenticated
+  with the provider.
 
-Cloud providers for which the Terraform provider supports authenticated
-environments include
+We encourage the latter approach where supported:
+
+- Simplifies the template.
+- Keeps provider credentials out of Coder's database, making it a less valuable
+  target for attackers.
+- Compatible with agent-based authentication schemes, which handle credential
+  rotation or ensure the credentials are not written to disk.
+
+Generally, you can set up an environment to provide credentials to Coder in
+these ways:
+
+- A well-known location on disk. For example, `~/.aws/credentials` for AWS on
+  POSIX systems.
+- Environment variables.
+
+It is usually sufficient to authenticate using the CLI or SDK for the provider
+before running Coder, but check the Terraform provider's documentation for
+details.
+
+These platforms have Terraform providers that support authenticated
+environments:
 
 - [Google Cloud](https://registry.terraform.io/providers/hashicorp/google/latest/docs)
 - [Amazon Web Services](https://registry.terraform.io/providers/hashicorp/aws/latest/docs)
 - [Microsoft Azure](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs)
 - [Kubernetes](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs)
 
-Additional providers may be supported; check the
+Other providers might also support authenticated environments. Check the
 [documentation of the Terraform provider](https://registry.terraform.io/browse/providers)
 for details.
-
-The way these generally work is via the credentials being available to Coder
-either in some well-known location on disk (e.g. `~/.aws/credentials` for AWS on
-posix systems), or via environment variables. It is usually sufficient to
-authenticate using the CLI or SDK for the cloud provider before running Coder
-for this to work, but check the Terraform provider documentation for details.