docs: clarify dev containers entry point and reduce callouts (#21188)

mafredri · web-flow · commit ea9f003cdde8 · 2025-12-09T16:37:19.000+02:00
The user guide jumped straight into integration details without explaining what dev containers are. Now it opens with a brief orientation linking to the spec, then explains this guide covers the Docker-based approach. Converted several NOTE callouts to prose where they were just cross-references or stacked unnecessarily. The Envbuilder index note was reframed to lead with its strengths rather than "we recommend the other thing." Also updates platform support to Linux only per current status. Refs #21157
diff --git a/docs/admin/integrations/devcontainers/envbuilder/index.md b/docs/admin/integrations/devcontainers/envbuilder/index.md
@@ -6,13 +6,12 @@ Unlike the [Dev Containers integration](../integration.md),
 Envbuilder transforms the workspace image itself rather than running containers
 inside the workspace.
 
-> [!NOTE]
->
-> For most use cases, we recommend the
-> [Dev Containers integration](../integration.md),
-> which uses the standard `@devcontainers/cli` and Docker. Envbuilder is an
-> alternative for environments where Docker is not available or for
-> administrator-controlled dev container workflows.
+Envbuilder is well-suited for Kubernetes-native deployments without privileged
+containers, environments where Docker is unavailable or restricted, and
+workflows where administrators need infrastructure-level control over image
+builds, caching, and security scanning. For workspaces with Docker available,
+the [Dev Containers Integration](../integration.md) offers container management
+with dashboard visibility and multi-container support.
 
 Dev containers provide developers with increased autonomy and control over their
 Coder cloud development environments.
diff --git a/docs/admin/integrations/devcontainers/integration.md b/docs/admin/integrations/devcontainers/integration.md
@@ -1,14 +1,13 @@
 # Configure a template for Dev Containers
 
-> [!NOTE]
-> For environments without Docker, see [Envbuilder](./envbuilder/index.md) as an alternative.
+This guide covers the Dev Containers Integration, which uses Docker. For
+environments without Docker, see [Envbuilder](./envbuilder/index.md) as an
+alternative.
 
 To enable Dev Containers in workspaces, configure your template with the Dev Containers
 modules and configurations outlined in this doc.
 
-> [!NOTE]
->
-> Dev Containers require a **Linux or macOS workspace**. Windows is not supported.
+Dev Containers are currently not supported in Windows or macOS workspaces.
 
 ## Configuration Modes
 
@@ -66,19 +65,10 @@ resource "coder_devcontainer" "my-repository" {
 }
 ```
 
-> [!NOTE]
->
-> The `workspace_folder` attribute must specify the location of the dev
-> container's workspace and should point to a valid project folder containing a
-> `devcontainer.json` file.
-
-<!-- nolint:MD028/no-blanks-blockquote -->
-
-> [!TIP]
->
-> Consider using the [`git-clone`](https://registry.coder.com/modules/git-clone)
-> module to ensure your repository is cloned into the workspace folder and ready
-> for automatic startup.
+The `workspace_folder` attribute must point to a valid project folder containing
+a `devcontainer.json` file. Consider using the
+[`git-clone`](https://registry.coder.com/modules/git-clone) module to ensure
+your repository is cloned and ready for automatic startup.
 
 For multi-repo workspaces, define multiple `coder_devcontainer` resources, each
 pointing to a different repository. Each one runs as a separate sub-agent with
diff --git a/docs/manifest.json b/docs/manifest.json
@@ -321,7 +321,7 @@
 					"icon_path": "./images/icons/circle-dot.svg"
 				},
 				{
-					"title": "Dev Containers Integration",
+					"title": "Dev Containers",
 					"description": "Run containerized development environments in your Coder workspace using the dev containers specification.",
 					"path": "./user-guides/devcontainers/index.md",
 					"icon_path": "./images/icons/container.svg",
diff --git a/docs/user-guides/devcontainers/index.md b/docs/user-guides/devcontainers/index.md
@@ -1,16 +1,15 @@
-# Dev Containers Integration
+# Dev Containers
 
-The Dev Containers integration enables seamless creation and management of dev
-containers in Coder workspaces. This feature leverages the
-[`@devcontainers/cli`](https://github.com/devcontainers/cli) and
-[Docker](https://www.docker.com) to provide a streamlined development
-experience.
+[Dev containers](https://containers.dev/) define your development environment
+as code using a `devcontainer.json` file. Coder's Dev Containers integration
+uses the [`@devcontainers/cli`](https://github.com/devcontainers/cli) and
+[Docker](https://www.docker.com) to seamlessly build and run these containers,
+with management in your dashboard.
 
-> [!NOTE]
-> This guide covers the Dev Containers Integration, which uses Docker.
-> For environments without Docker, administrators can configure
-> [Envbuilder](../../admin/integrations/devcontainers/envbuilder/index.md)
-> as an alternative.
+This guide covers the Dev Containers integration. For workspaces without Docker,
+administrators can configure
+[Envbuilder](../../admin/integrations/devcontainers/envbuilder/index.md) instead,
+which builds the workspace image itself from your dev container configuration.
 
 ## Prerequisites
 
@@ -20,7 +19,7 @@ experience.
 
 Dev Containers integration is enabled by default. Your workspace needs Docker
 (via Docker-in-Docker or a mounted socket) and the devcontainers CLI. Most
-templates with Dev Containers support include both—see
+templates with Dev Containers support include both. See
 [Configure a template for dev containers](../../admin/integrations/devcontainers/integration.md)
 for setup details.
 
@@ -115,8 +114,8 @@ in your `devcontainer.json`.
 
 ## Limitations
 
-- **Linux and macOS only** — Dev Containers are not supported on Windows
-  workspaces
+- **Linux only**: Dev Containers are currently not supported in Windows or
+  macOS workspaces
 - Changes to `devcontainer.json` require manual rebuild using the dashboard
   button
 - The `forwardPorts` property in `devcontainer.json` with `host:port` syntax

Original file line number	Diff line number	Diff line change
`@@ -321,7 +321,7 @@`
`321`	`321`	`"icon_path": "./images/icons/circle-dot.svg"`
`322`	`322`	`},`
`323`	`323`	`{`
`324`		`- "title": "Dev Containers Integration",`
	`324`	`+ "title": "Dev Containers",`
`325`	`325`	`"description": "Run containerized development environments in your Coder workspace using the dev containers specification.",`
`326`	`326`	`"path": "./user-guides/devcontainers/index.md",`
`327`	`327`	`"icon_path": "./images/icons/container.svg",`