coder · matifali · Oct 16, 2023 · Aug 16, 2023 · Aug 17, 2023 · Aug 17, 2023
diff --git a/docs/images/autostart.png b/docs/images/autostart.png
diff --git a/docs/images/autostop.png b/docs/images/autostop.png
diff --git a/docs/images/creating-workspace-ui.png b/docs/images/creating-workspace-ui.png
diff --git a/docs/images/schedule.png b/docs/images/schedule.png
diff --git a/docs/images/workspace-update.png b/docs/images/workspace-update.png
diff --git a/docs/workspaces.md b/docs/workspaces.md
@@ -1,11 +1,31 @@
 # Workspaces
 
-Workspaces contain the IDEs, dependencies, and configuration information needed
-for software development.
+A workspace is the environment that a developer works in. Developers
+in a team each work from their own workspace and can use [multiple
+IDEs](./ides.md).
 
-## Create workspaces
+A developer creates a workspace from a [shared
+template](./templates/index.md). This lets an entire team work in
+environments that are identically configured and provisioned with the
+same resources.
 
-Each Coder user has their own workspaces created from [shared templates](./templates/index.md):
+
+## Creating workspaces
+
+You can create a workspace in the UI. Log in to your Coder instance,
+go to the **Templates** tab, find the template you need, and select
+**Create Workspace**.
+
+![Creating a workspace in the UI](./images/creating-workspace-ui.png)
+
+When you create a workspace, you will be prompted to give it a name. You
+might also be prompted to set some parameters that the template
+provides.
+
+You can manage your existing templates in the **Workspaces**
+tab.
+
+You can also create a workspace from the command line:
 
 ```console
 # create a workspace from the template; specify any variables
@@ -15,76 +35,97 @@ coder create --template="<templateName>" <workspaceName>
 coder show <workspace-name>
 ```
 
-## IDEs
-
-Coder [supports multiple IDEs](./ides.md) for use with your workspaces.
+## Workspace filtering
 
-## Workspace lifecycle
+In the Coder UI, you can filter your workspaces using pre-defined
+filters or Coder's filter query. For example, you can find the
+workspaces that you own or that are currently running.
 
-Workspaces in Coder are started and stopped, often based on whether there was
-any activity or if there was a [template update](./templates/index.md#Start/stop) available.
+The following filters are supported:
 
-Resources are often destroyed and re-created when a workspace is restarted,
-though the exact behavior depends on the template. For more
-information, see [Resource Persistence](./templates/resource-persistence.md).
+- `owner` - Represents the `username` of the owner. You can also use `me` as a convenient alias for the logged-in user.
+- `template` - Specifies the name of the template.
+- `status` - Indicates the status of the workspace. For a list of supported statuses, see [WorkspaceStatus documentation](https://pkg.go.dev/github.com/coder/coder/codersdk#WorkspaceStatus).
 
-> ⚠️ To avoid data loss, refer to your template documentation for information on
-> where to store files, install software, etc., so that they persist. Default
-> templates are documented in [../examples/templates](https://github.com/coder/coder/tree/c6b1daabc5a7aa67bfbb6c89966d728919ba7f80/examples/templates).
->
-> You can use `coder show <workspace-name>` to see which resources are
-> persistent and which are ephemeral.
 
-When a workspace is deleted, all of the workspace's resources are deleted.
+## Starting and stopping workspaces
 
-## Workspace scheduling
+By default, you manually start and stop workspaces as you need. You
+can also schedule a workspace to start and stop automatically.
 
-By default, workspaces are manually turned on/off by the user. However, a schedule
-can be defined on a per-workspace basis to automate the workspace start/stop.
+To set a workspace's schedule, go to the workspace, then **Settings** > **Schedule**.
 
 ![Scheduling UI](./images/schedule.png)
 
-### Autostart
+Coder might also stop a workspace automatically if there is a [template
+update](./templates/index.md#Start/stop) available.
+
+
+### Autostart and autostop
 
-The autostart feature automates the workspace build at a user-specified time
-and day(s) of the week. In addition, users can select their preferred timezone.
+Use autostart to start a workspace at a specified time and which days of the
+week. Also, you can choose your preferred timezone.
 
 ![Autostart UI](./images/autostart.png)
 
-### Autostop
+Use autostop to stop a workspace after a number of hours. Autostop
+won't stop a workspace if you're still using it. It waits for
+another hour before checking again. Coder checks for active
+connections in the IDE, SSH, Port Forwarding, and coder_app.
 
-The autostop feature shuts off workspaces after given number of hours in the "on"
-state. If Coder detects workspace connection activity, the autostop timer is bumped up
-one hour. IDE, SSH, Port Forwarding, and coder_app activity trigger this bump.
+![Autostop UI](./images/autostop.png)
 
-![autostop UI](./images/autostop.png)
 
 ### Max lifetime
 
-Max lifetime is a template-level setting that determines the number of hours a
-workspace can run before it is automatically shutdown, regardless of any
-active connections. This setting ensures workspaces do not run in perpetuity
-when connections are left open inadvertently.
+Max lifetime is a template setting that determines the number of hours
+a workspace will run before Coder automatically stops it, regardless
+of any active connections. Use this setting to ensure that workspaces
+do not run in perpetuity when connections are left open inadvertently.
+
 
 ## Updating workspaces
 
-Use the following command to update a workspace to the latest template version.
-The workspace will be stopped and started:
+After updating the default version of the template that a workspace
+was created from, you can update the workspace.
+
+![Updating a workspace](./images/workspace-update.png)
+
+If the workspace is running, Coder stops it, updates it, then starts
+the workspace again.
+
+On the command line:
 
 ```console
 coder update <workspace-name>
 ```
 
+
 ## Repairing workspaces
 
-Use the following command to re-enter template input
-variables in an existing workspace. This command is useful when a workspace fails
-to build because its state is out of sync with the template.
+Use the following command to re-enter template input variables in an
+existing workspace. This command is useful when a workspace fails to
+build because its state is out of sync with the template.
 
 ```console
 coder update <your workspace name> --always-prompt
 ```
 
+## Workspace resources
+
+Resources are often destroyed and re-created when a workspace is restarted,
+though the exact behavior depends on the template. For more
+information, see [Resource Persistence](./templates/resource-persistence.md).
+
+> ⚠️ To avoid data loss, refer to your template documentation for information on
+> where to store files, install software, etc., so that they persist. Default
+> templates are documented in [../examples/templates](https://github.com/coder/coder/tree/c6b1daabc5a7aa67bfbb6c89966d728919ba7f80/examples/templates).
+>
+> You can use `coder show <workspace-name>` to see which resources are
+> persistent and which are ephemeral.
+
+When a workspace is deleted, all of the workspace's resources are deleted.
+
 ## Logging
 
 Coder stores macOS and Linux logs at the following locations:
@@ -97,19 +138,6 @@ Coder stores macOS and Linux logs at the following locations:
 
 > Note: Logs are truncated once they reach 5MB in size.
 
-## Workspace filtering
-
-In the Coder UI, you can filter your workspaces using pre-defined filters or employing the Coder's filter query. Take a look at the following examples to understand how to use the Coder's filter query:
-
-- To find the workspaces that you own, use the filter `owner:me`.
-- To find workspaces that are currently running, use the filter `status:running`.
-
-The following filters are supported:
-
-- `owner` - Represents the `username` of the owner. You can also use `me` as a convenient alias for the logged-in user.
-- `template` - Specifies the name of the template.
-- `status` - Indicates the status of the workspace. For a list of supported statuses, please refer to the [WorkspaceStatus documentation](https://pkg.go.dev/github.com/coder/coder/codersdk#WorkspaceStatus).
-
 ---
 
 ## Up next