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/devcontainers.md

@@ -2,31 +2,31 @@
 
 [Devcontainers](https://containers.dev) are an open source specification for
 defining development environments.
+
 [envbuilder](https://github.com/coder/envbuilder) is an open source project by
 Coder that runs devcontainers via Coder templates and your underlying
-infrastructure.
+infrastructure. It can run on Docker or Kubernetes.
 
 There are several benefits to adding a devcontainer-compatible template to
 Coder:
 
 - Drop-in migration from Codespaces (or any existing repositories that use
   devcontainers)
-- Easier to start projects from Coder (new workspace, pick starter devcontainer)
+- Easier to start projects from Coder. Just create a new workspace then pick a
+  starter devcontainer.
 - Developer teams can "bring their own image." No need for platform teams to
   manage complex images, registries, and CI pipelines.
 
 ## How it works
 
-- Coder admins add a devcontainer-compatible template to Coder (envbuilder can
-  run on Docker or Kubernetes)
+A Coder admin adds a devcontainer-compatible template to Coder (envbuilder).
+Then developers enter their repository URL as a [parameter](./parameters.md)
+when they create their workspace.
+[envbuilder](https://github.com/coder/envbuilder) clones the repo and builds a
+container from the `devcontainer.json` specified in the repo.
 
-- Developers enter their repository URL as a [parameter](./parameters.md) when
-  they create their workspace. [envbuilder](https://github.com/coder/envbuilder)
-  clones the repo and builds a container from the `devcontainer.json` specified
-  in the repo.
-
-- Developers can edit the `devcontainer.json` in their workspace to rebuild to
-  iterate on their development environments.
+Developers can edit the `devcontainer.json` in their workspace to rebuild to
+iterate on their development environments.
 
 ## Example templates
 
@@ -35,13 +35,13 @@ Coder:
 
 ![Devcontainer parameter screen](../images/templates/devcontainers.png)
 
-[Parameters](./parameters.md) can be used to prompt the user for a repo URL when
-they are creating a workspace.
+Your template can prompt the user for a repo URL with
+[Parameters](./parameters.md).
 
 ## Authentication
 
-You may need to authenticate to your container registry (e.g. Artifactory) or
-git provider (e.g. GitLab) to use envbuilder. Refer to the
+You may need to authenticate to your container registry, such as Artifactory, or
+git provider such as GitLab, to use envbuilder. See the
 [envbuilder documentation](https://github.com/coder/envbuilder/) for more
 information.